API
Idempotencia
Toda validación exige Idempotency-Key: entre 16 y 128 caracteres, empieza por letra o número y admite A-Z a-z 0-9 . _ ~ : -. Usa una clave por pedido.
Reglas#
- Mismo ámbito: comercio + integración. La misma clave en otra integración es otra operación.
- Mismo
Idempotency-Keyy el mismo cuerpo (incluidoevent_at) → réplica de la respuesta original, sin nuevo cobro (REPLAY_NOT_CHARGED). - Misma clave con otro cuerpo →
409 IDEMPOTENCY_CONFLICT. Usa otra clave solo si es realmente otro pedido. - Misma clave mientras la primera sigue en curso →
409 OPERATION_PENDING. Consulta el readback; no cambies de clave.
Cuándo reintentar#
| Respuesta | Qué hacer |
|---|---|
503 SERVICE_UNAVAILABLE | Reintenta con la misma clave y el mismo cuerpo, con espera creciente y un tope de intentos. Puede que el servicio sí haya procesado la solicitud: el reintento recupera ese resultado sin cobrar dos veces. |
429 RATE_LIMITED | Espera los segundos de Retry-After y reintenta. |
409 OPERATION_PENDING | Consulta el readback hasta que haya resultado. |
Cualquier DO_NOT_RETRY | No reintentes; corrige la causa. |
Las respuestas selladas se conservan 7 días (valor configurado, sujeto a confirmación): pasado ese plazo, la misma clave vuelve a ejecutarse. Usa siempre una clave nueva por pedido.
Genera event_at una vez por pedido y reutilízalo en los reintentos.