Idempotencia

Si una petición que cuesta créditos se corta (red, tiempo de espera), no sabes si llegó. Con una Idempotency-Key puedes repetirla sin miedo: nunca se cobra dos veces.

Cómo se usa

Genera una clave única por acción, por ejemplo un UUID, y envíala en la cabecera Idempotency-Key de POST /jobs.
Si tienes que reintentar, envía la misma clave y el mismo cuerpo.

Idempotency-Key: f3b1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d

Qué responde la API

Caso	Respuesta
Primera vez con esa clave	Se ejecuta normalmente.
Misma clave y mismo cuerpo	La misma respuesta de la primera vez, sin volver a ejecutarla ni cobrarla, con la cabecera `Idempotent-Replayed: true`.
Misma clave, la primera aún en curso	`409` `idempotency_key_in_use`: espera y repite.
Misma clave con otro cuerpo	`422` `idempotency_key_reused`: usa una clave nueva.

Repetición · cabeceras de la respuesta

Location: /api/v1/jobs/394730eb-3747-4fd2-9e06-9a945e9f12fb
Idempotent-Replayed: true

Respuesta · 422

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#idempotency_key_reused",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "This Idempotency-Key was already used with a different request.",
  "code": "idempotency_key_reused"
}

Detalles

Las claves duran 24 horas y son de tu cuenta: otra cuenta puede usar la misma sin problema.
Una clave tiene de 1 a 255 caracteres imprimibles.
Los errores no se guardan: si la primera petición falló (por ejemplo, 402 sin créditos), repetirla con la misma clave la vuelve a ejecutar.
La cabecera es opcional, pero recomendable en todo lo que cuesta créditos (ver Créditos).