[{"data":1,"prerenderedAt":609},["ShallowReactive",2],{"docs:\u002Fdocs\u002Fidempotencia-y-errores":3,"docs-surround:\u002Fdocs\u002Fidempotencia-y-errores":585,"docs-navigation":591},{"id":4,"title":5,"body":6,"description":577,"extension":578,"meta":579,"navigation":580,"path":581,"seo":582,"stem":583,"__hash__":584},"docs\u002Fdocs\u002F6.idempotencia-y-errores.md","Idempotencia y errores",{"type":7,"value":8,"toc":571},"minimark",[9,14,34,100,156,173,176,180,183,278,379,383,518,522,559,567],[10,11,13],"h2",{"id":12},"idempotencia","Idempotencia",[15,16,17,18,25,26,29,30,33],"p",{},"Una red inestable puede cortar una petición después de que Paygumi la procesó. Para reintentar sin crear dos suscripciones ni dos sesiones, envía la cabecera ",[19,20,21],"strong",{},[22,23,24],"code",{},"Idempotency-Key"," en todo ",[22,27,28],{},"POST"," de ",[22,31,32],{},"\u002Fv1",":",[35,36,41],"pre",{"className":37,"code":38,"language":39,"meta":40,"style":40},"language-bash shiki shiki-themes github-light github-dark","curl https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fsubscriptions \\\n  -H \"Authorization: Bearer pgm_test_...\" \\\n  -H \"Idempotency-Key: 9b1f6c2e-4d3a-4c8e-8f0a-2e7d5b1c9a33\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"customer_id\": \"cus_01JB86R800ABCDEFGHJKMNPQRS\", \"plan_id\": \"pln_01JB86R800ABCDEFGHJKMNPQRS\" }'\n","bash","",[22,42,43,60,71,81,91],{"__ignoreMap":40},[44,45,48,52,56],"span",{"class":46,"line":47},"line",1,[44,49,51],{"class":50},"sScJk","curl",[44,53,55],{"class":54},"sZZnC"," https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fsubscriptions",[44,57,59],{"class":58},"sj4cs"," \\\n",[44,61,63,66,69],{"class":46,"line":62},2,[44,64,65],{"class":58},"  -H",[44,67,68],{"class":54}," \"Authorization: Bearer pgm_test_...\"",[44,70,59],{"class":58},[44,72,74,76,79],{"class":46,"line":73},3,[44,75,65],{"class":58},[44,77,78],{"class":54}," \"Idempotency-Key: 9b1f6c2e-4d3a-4c8e-8f0a-2e7d5b1c9a33\"",[44,80,59],{"class":58},[44,82,84,86,89],{"class":46,"line":83},4,[44,85,65],{"class":58},[44,87,88],{"class":54}," \"Content-Type: application\u002Fjson\"",[44,90,59],{"class":58},[44,92,94,97],{"class":46,"line":93},5,[44,95,96],{"class":58},"  -d",[44,98,99],{"class":54}," '{ \"customer_id\": \"cus_01JB86R800ABCDEFGHJKMNPQRS\", \"plan_id\": \"pln_01JB86R800ABCDEFGHJKMNPQRS\" }'\n",[101,102,103,107,114,123,132,141],"ul",{},[104,105,106],"li",{},"La clave la eliges tú: de 1 a 255 caracteres ASCII visibles. Se recomienda un UUID v4 nuevo por cada operación, que guardas para reintentar.",[104,108,109,110,113],{},"Es única por cuenta y entorno de la API key, y la respuesta se guarda ",[19,111,112],{},"24 horas",".",[104,115,116,119,120,113],{},[19,117,118],{},"Misma clave y misma petición"," (método, ruta con query y cuerpo idénticos byte a byte): devuelve la respuesta guardada, sin volver a ejecutar, con la cabecera ",[22,121,122],{},"Idempotent-Replayed: true",[104,124,125,128,129,113],{},[19,126,127],{},"Misma clave con otra petición:"," ",[22,130,131],{},"422 idempotency_key_reused",[104,133,134,128,137,140],{},[19,135,136],{},"Misma clave mientras la primera sigue en curso:",[22,138,139],{},"409 idempotency_key_in_use","; reintenta en unos segundos.",[104,142,143,144,147,148,151,152,155],{},"Se guardan las respuestas ",[22,145,146],{},"2xx"," y ",[22,149,150],{},"4xx",". Las ",[22,153,154],{},"5xx"," no: reintentar con la misma clave vuelve a ejecutar.",[15,157,158,159,162,163,165,166,168,169,172],{},"Las sesiones de checkout y de portal devuelven su ",[22,160,161],{},"url"," una sola vez. En una repetición por ",[22,164,24],{}," la ",[22,167,161],{}," viene en ",[22,170,171],{},"null",": si la perdiste, crea otra sesión.",[15,174,175],{},"Los cobros de cada periodo tienen su propia protección: Paygumi nunca cobra dos veces el mismo periodo de una suscripción.",[10,177,179],{"id":178},"formato-de-los-errores","Formato de los errores",[15,181,182],{},"Todos los errores tienen el mismo cuerpo:",[35,184,188],{"className":185,"code":186,"language":187,"meta":40,"style":40},"language-json shiki shiki-themes github-light github-dark","{\n  \"error\": {\n    \"type\": \"invalid_request\",\n    \"code\": \"plan_archived\",\n    \"message\": \"El plan está archivado.\",\n    \"param\": \"plan_id\",\n    \"request_id\": \"req_01JB86R800ABCDEFGHJKMNPQRS\"\n  }\n}\n","json",[22,189,190,196,204,218,230,242,255,266,272],{"__ignoreMap":40},[44,191,192],{"class":46,"line":47},[44,193,195],{"class":194},"sVt8B","{\n",[44,197,198,201],{"class":46,"line":62},[44,199,200],{"class":58},"  \"error\"",[44,202,203],{"class":194},": {\n",[44,205,206,209,212,215],{"class":46,"line":73},[44,207,208],{"class":58},"    \"type\"",[44,210,211],{"class":194},": ",[44,213,214],{"class":54},"\"invalid_request\"",[44,216,217],{"class":194},",\n",[44,219,220,223,225,228],{"class":46,"line":83},[44,221,222],{"class":58},"    \"code\"",[44,224,211],{"class":194},[44,226,227],{"class":54},"\"plan_archived\"",[44,229,217],{"class":194},[44,231,232,235,237,240],{"class":46,"line":93},[44,233,234],{"class":58},"    \"message\"",[44,236,211],{"class":194},[44,238,239],{"class":54},"\"El plan está archivado.\"",[44,241,217],{"class":194},[44,243,245,248,250,253],{"class":46,"line":244},6,[44,246,247],{"class":58},"    \"param\"",[44,249,211],{"class":194},[44,251,252],{"class":54},"\"plan_id\"",[44,254,217],{"class":194},[44,256,258,261,263],{"class":46,"line":257},7,[44,259,260],{"class":58},"    \"request_id\"",[44,262,211],{"class":194},[44,264,265],{"class":54},"\"req_01JB86R800ABCDEFGHJKMNPQRS\"\n",[44,267,269],{"class":46,"line":268},8,[44,270,271],{"class":194},"  }\n",[44,273,275],{"class":46,"line":274},9,[44,276,277],{"class":194},"}\n",[279,280,281,294],"table",{},[282,283,284],"thead",{},[285,286,287,291],"tr",{},[288,289,290],"th",{},"Campo",[288,292,293],{},"Uso",[295,296,297,308,324,334,348,365],"tbody",{},[285,298,299,305],{},[300,301,302],"td",{},[22,303,304],{},"type",[300,306,307],{},"Categoría (tabla de abajo).",[285,309,310,314],{},[300,311,312],{},[22,313,22],{},[300,315,316,317,320,321],{},"Identificador estable en ",[22,318,319],{},"snake_case",". ",[19,322,323],{},"Decide por este campo.",[285,325,326,331],{},[300,327,328],{},[22,329,330],{},"message",[300,332,333],{},"Texto para personas; puede cambiar, no lo parsees.",[285,335,336,341],{},[300,337,338],{},[22,339,340],{},"param",[300,342,343,344,347],{},"Campo de la entrada que causó el error, si aplica (p. ej. ",[22,345,346],{},"customer.email",").",[285,349,350,355],{},[300,351,352],{},[22,353,354],{},"resource_id",[300,356,357,358,361,362,347],{},"En algunos ",[22,359,360],{},"409",", el id del recurso en conflicto (p. ej. el cliente que ya tiene ese ",[22,363,364],{},"external_id",[285,366,367,372],{},[300,368,369],{},[22,370,371],{},"request_id",[300,373,374,375,378],{},"Igual a la cabecera ",[22,376,377],{},"X-Request-Id",". Inclúyelo cuando pidas soporte.",[10,380,382],{"id":381},"tipos-de-error","Tipos de error",[279,384,385,399],{},[282,386,387],{},[285,388,389,393,396],{},[288,390,391],{},[22,392,304],{},[288,394,395],{},"HTTP",[288,397,398],{},"Qué hacer",[295,400,401,417,430,443,456,471,488,503],{},[285,402,403,408,411],{},[300,404,405],{},[22,406,407],{},"invalid_request",[300,409,410],{},"400, 409, 413, 415, 422",[300,412,413,414,416],{},"Corrige la petición: JSON mal formado, un campo inválido (",[22,415,340],{},") o una operación que el estado no permite. No reintentes igual.",[285,418,419,424,427],{},[300,420,421],{},[22,422,423],{},"unauthorized",[300,425,426],{},"401",[300,428,429],{},"API key ausente, revocada o de otro formato.",[285,431,432,437,440],{},[300,433,434],{},[22,435,436],{},"forbidden",[300,438,439],{},"403",[300,441,442],{},"La credencial no autoriza la operación.",[285,444,445,450,453],{},[300,446,447],{},[22,448,449],{},"not_found",[300,451,452],{},"404",[300,454,455],{},"El recurso no existe o es de otro entorno.",[285,457,458,463,465],{},[300,459,460],{},[22,461,462],{},"conflict",[300,464,360],{},[300,466,467,468,470],{},"Conflicto con el estado actual (",[22,469,22],{}," dice cuál).",[285,472,473,478,481],{},[300,474,475],{},[22,476,477],{},"rate_limited",[300,479,480],{},"429",[300,482,483,484,487],{},"Espera lo que diga ",[22,485,486],{},"Retry-After"," y reintenta.",[285,489,490,495,498],{},[300,491,492],{},[22,493,494],{},"gateway_error",[300,496,497],{},"502",[300,499,500,501,113],{},"Wompi no respondió. Reintenta con la misma ",[22,502,24],{},[285,504,505,510,513],{},[300,506,507],{},[22,508,509],{},"internal",[300,511,512],{},"500",[300,514,515,516,113],{},"Error de Paygumi. Reintenta con la misma ",[22,517,24],{},[10,519,521],{"id":520},"cuándo-reintentar","Cuándo reintentar",[101,523,524,550],{},[104,525,526,529,530,532,533,532,535,537,538,540,541,147,543,546,547,549],{},[19,527,528],{},"Sí:"," errores de red, ",[22,531,512],{},", ",[22,534,497],{},[22,536,480],{}," (tras ",[22,539,486],{},"), ",[22,542,139],{},[22,544,545],{},"409 subscription_version_conflict",". Usa la misma ",[22,548,24],{}," y espera cada vez más entre intentos.",[104,551,552,555,556,558],{},[19,553,554],{},"No:"," el resto de ",[22,557,150],{},". Repetir la misma petición dará el mismo error.",[15,560,561,562,113],{},"Los códigos de cada operación están en la ",[563,564,566],"a",{"href":565},"\u002Fdocs\u002Fapi","referencia de la API",[568,569,570],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}",{"title":40,"searchDepth":73,"depth":73,"links":572},[573,574,575,576],{"id":12,"depth":62,"text":13},{"id":178,"depth":62,"text":179},{"id":381,"depth":62,"text":382},{"id":520,"depth":62,"text":521},"Reintenta peticiones sin repetir su efecto con Idempotency-Key y maneja los errores de la API por su código.","md",{},true,"\u002Fdocs\u002Fidempotencia-y-errores",{"title":5,"description":577},"docs\u002F6.idempotencia-y-errores","I5iGRL3gydX9c_3MxMAZBHA7hzGc3AmNj4gSkU53Dys",[586,590],{"title":587,"path":588,"stem":589,"children":-1},"Portal del cliente","\u002Fdocs\u002Fportal-del-cliente","docs\u002F5.portal-del-cliente",null,[592,595,598,601,604,607,608],{"title":593,"path":594},"Introducción","\u002Fdocs",{"title":596,"path":597},"Primeros pasos","\u002Fdocs\u002Fprimeros-pasos",{"title":599,"path":600},"Crear una sesión de checkout","\u002Fdocs\u002Fsesiones-de-checkout",{"title":602,"path":603},"Suscripciones y estados de acceso","\u002Fdocs\u002Fsuscripciones-y-acceso",{"title":605,"path":606},"Webhooks","\u002Fdocs\u002Fwebhooks",{"title":587,"path":588},{"title":5,"path":581},1794279320112]