Idempotencia y errores

Reintenta peticiones sin repetir su efecto con Idempotency-Key y maneja los errores de la API por su código.

Idempotencia

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 Idempotency-Key en todo POST de /v1:

curl https://api.paygumi.com/v1/subscriptions \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 9b1f6c2e-4d3a-4c8e-8f0a-2e7d5b1c9a33" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_01JB86R800ABCDEFGHJKMNPQRS", "plan_id": "pln_01JB86R800ABCDEFGHJKMNPQRS" }'

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.
Es única por cuenta y entorno de la API key, y la respuesta se guarda 24 horas.
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 Idempotent-Replayed: true.
Misma clave con otra petición: 422 idempotency_key_reused.
Misma clave mientras la primera sigue en curso: 409 idempotency_key_in_use; reintenta en unos segundos.
Se guardan las respuestas 2xx y 4xx. Las 5xx no: reintentar con la misma clave vuelve a ejecutar.

Las sesiones de checkout y de portal devuelven su url una sola vez. En una repetición por Idempotency-Key la url viene en null: si la perdiste, crea otra sesión.

Los cobros de cada periodo tienen su propia protección: Paygumi nunca cobra dos veces el mismo periodo de una suscripción.

Formato de los errores

Todos los errores tienen el mismo cuerpo:

{
  "error": {
    "type": "invalid_request",
    "code": "plan_archived",
    "message": "El plan está archivado.",
    "param": "plan_id",
    "request_id": "req_01JB86R800ABCDEFGHJKMNPQRS"
  }
}

Campo	Uso
`type`	Categoría (tabla de abajo).
`code`	Identificador estable en `snake_case`. Decide por este campo.
`message`	Texto para personas; puede cambiar, no lo parsees.
`param`	Campo de la entrada que causó el error, si aplica (p. ej. `customer.email`).
`resource_id`	En algunos `409`, el id del recurso en conflicto (p. ej. el cliente que ya tiene ese `external_id`).
`request_id`	Igual a la cabecera `X-Request-Id`. Inclúyelo cuando pidas soporte.

Tipos de error

`type`	HTTP	Qué hacer
`invalid_request`	400, 409, 413, 415, 422	Corrige la petición: JSON mal formado, un campo inválido (`param`) o una operación que el estado no permite. No reintentes igual.
`unauthorized`	401	API key ausente, revocada o de otro formato.
`forbidden`	403	La credencial no autoriza la operación.
`not_found`	404	El recurso no existe o es de otro entorno.
`conflict`	409	Conflicto con el estado actual (`code` dice cuál).
`rate_limited`	429	Espera lo que diga `Retry-After` y reintenta.
`gateway_error`	502	Wompi no respondió. Reintenta con la misma `Idempotency-Key`.
`internal`	500	Error de Paygumi. Reintenta con la misma `Idempotency-Key`.

Cuándo reintentar

Sí: errores de red, 500, 502, 429 (tras Retry-After), 409 idempotency_key_in_use y 409 subscription_version_conflict. Usa la misma Idempotency-Key y espera cada vez más entre intentos.
No: el resto de 4xx. Repetir la misma petición dará el mismo error.

Los códigos de cada operación están en la referencia de la API.