Reintentos seguros con Idempotency-Key
Reintenta llamadas mutantes de la API sin crear pagos o payouts duplicados.
Envía Idempotency-Key en POST
Todas las rutas POST autenticadas bajo /v1/* aceptan un encabezado opcional Idempotency-Key (1–255 ASCII imprimible). Las claves se aíslan por entorno del tenant (live y test no las comparten). Sin el encabezado, el comportamiento no cambia.
- Misma clave + mismo método/ruta/cuerpo en 24h → se reenvía la respuesta almacenada con
Idempotent-Replayed: true. - Misma clave + cuerpo distinto → 409
idempotency_key_reused. - Misma clave mientras la primera solicitud sigue en curso → 409
idempotency_request_in_progress(reintenta luego). - Los 5xx y las interrupciones no se almacenan — reintentar con la misma clave es seguro.
Relación con externalRef
En pagos, externalRef sigue siendo solo correlación. En comerciantes y payouts, externalRef sigue siendo la clave de idempotencia del recurso e independe de Idempotency-Key.