Idempotencia

Toda operación que mueve dinero acepta Idempotency-Key. Manda una clave única por operación — tu propio id de transacción sirve.

curl -s -X POST $BASE/v1/payouts \
  -H "x-api-key: $KEY" \
  -H "Idempotency-Key: payout-2026-0001" \
  -H 'content-type: application/json' \
  -d '{"quoteId":"70ec44b5-…","method":"pago_movil","beneficiaryId":"8ade3e33-…"}'

Qué pasa con cada combinación

Situación	Resultado
Clave nueva	Se ejecuta
Misma clave, mismo cuerpo	Devuelve la respuesta original (mismo body, mismo código HTTP) sin volver a ejecutar
Misma clave, cuerpo distinto	`409 idempotency_key_reused`
La original sigue en curso	`409 idempotency_request_in_flight` — reintenta en unos segundos
La original falló	La reserva se libera: puedes reintentar con la misma clave

{ "error": {
    "type": "invalid_request_error", "code": "idempotency_key_reused",
    "message": "Esta Idempotency-Key ya se usó con un payload distinto: usa una key nueva",
    "request_id": "req_8a0312ba896772bc441134cd" } }

Cómo se compara

La huella es el método, la ruta con su query string y el cuerpo serializado. Reordenar las claves del JSON cuenta como cuerpo distinto, así que serializa siempre igual. La clave está aislada por programa, y sólo se aplica a peticiones que no son GET.

Ventanas


Vida de la clave	24 horas. Pasadas, la misma clave vuelve a ser nueva
Petición interrumpida	Si una petición se corta sin responder, la clave queda reclamable al cabo de ~60 segundos

La segunda protección: la cotización

La cotización es de un solo uso: la segunda dispersión con el mismo quoteId recibe 409 quote_already_consumed, aunque cambies la Idempotency-Key.

Qué reintentar y con qué clave

Respuesta	Reintento	Clave
`502 provider_error`	Sí	La misma
`503 no_provider_available`	Sí, más tarde	La misma
`429 rate_limited`	Sí, más despacio	La misma
Timeout / conexión cortada	Sí	La misma
`4xx` de validación	No sin corregir	Nueva, porque el cuerpo cambia
`status: "failed"`	Sí, con otra cotización	Nueva
`status: "unknown"`	Nunca	—

Ver cuando algo falla.