Idempotencia
Un error de red puede dejarte sin saber si una solicitud llegó a la API. Reintentar es lo correcto, pero en trabajos costosos, como un job de video o una generación larga, no quieres que se ejecute dos veces. Envía un header Idempotency-Key y un reintento con la misma clave se reconoce como la misma solicitud.
curl https://api.inferray.com/v1/videos \
-H "Authorization: Bearer $INFERRAY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d3c2e1a-onboarding-video-42" \
-d '{"model": "veo-3.1-fast-generate-preview", "prompt": "A paper boat on a pond", "seconds": 8}'
La clave es cualquier string de hasta 256 caracteres. Un UUID aleatorio por solicitud lógica funciona bien: genéralo una sola vez, antes del primer intento, y reutilízalo en cada reintento.
Qué pasa con una repetición
| Envías | Recibes |
|---|---|
| La misma clave y el mismo body, para un video o una respuesta almacenada | El job o la respuesta que creó la primera solicitud. Nada se ejecuta ni se cobra de nuevo. |
| La misma clave y el mismo body, para cualquier otra solicitud | Un 409 que indica que la solicitud ya se envió. No se volvió a ejecutar. |
| La misma clave con un body o un modelo distinto | Un 409. Una clave pertenece a la primera solicitud con la que se usó. |
| Una clave nueva | Una solicitud nueva. |
Una clave se recuerda durante un día para las solicitudes normales, siete días para los jobs de video y treinta días para las respuestas almacenadas.
Cuándo usarla
- Siempre en la generación de video, que es lenta y se cobra por segundo.
- En cualquier solicitud que tu código reintente automáticamente tras timeouts o errores de conexión.
- En colas de jobs que pueden entregar la misma tarea más de una vez.
Sin el header, cada solicitud se trata como nueva, que es lo que normalmente quieres en un uso interactivo.