Idempotencia
Reintenta una operación sin crear una segunda compra o devolución.
Envía Idempotency-Key en cada mutación de la API de servidor. La clave debe tener entre 8 y 255 caracteres ASCII imprimibles, sin espacios.
curl https://api.billete.run/v1/checkouts \
-H "Authorization: Bearer $BILLETE_API_KEY" \
-H "Billete-Version: 2026-10-24" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: checkout-order-123" \
-d '{"items":[{"product":"prod_ejemplo","quantity":1}]}'Reglas de reintento
- Conserva la misma clave, método, ruta y cuerpo exacto para reintentar la misma operación.
- Usa una clave nueva para una operación nueva.
- Una respuesta repetida incluye
Idempotent-Replayed: true. - La ventana de conservación es de 24 horas. Fuera de ella, consulta el recurso antes de repetir una operación de dinero.
- Los errores de servidor no quedan guardados como una respuesta definitiva.
| Código | Qué significa |
|---|---|
idempotency_key_invalid | La clave tiene un formato inválido |
idempotency_key_reused | Se reutilizó con otra petición |
idempotency_request_in_progress | La operación sigue en curso; espera antes de reintentar |
idempotency_conflict | Repite la solicitud conservando la clave |
En el SDK
El cliente de servidor del SDK genera una clave por mutación y la conserva durante sus reintentos. Para repetir una llamada desde tu propio job, pasa una idempotencyKey estable. Ver ejemplo.