Idempotencia

Si una petición se corta por la red, no sabes si llegó. Con Idempotency-Key puedes reintentarla sin generar ni cobrar dos veces. Úsala en los POST que crean trabajo (crear, corregir, agregar tamaños e idiomas, exportar, subir archivos); las consultas GET no la necesitan.

Cómo funciona

• •Envía Idempotency-Key con un texto único, de hasta 200 caracteres. Un UUID funciona bien.
• •Misma clave y mismo cuerpo: recibes la misma respuesta, con el encabezado Idempotent-Replayed: true. No se vuelve a generar ni a cobrar.
• •Misma clave y otro cuerpo: error 422 (idempotency_mismatch).
• •Misma clave mientras la primera sigue en proceso: error 409 (conflict). Espera un momento y reintenta.
• •Solo se guardan las respuestas exitosas: si la petición falla, la clave queda libre.

Ejemplo

curl -X POST https://app.bannermotion.com/api/v1/banners \
  -H "Authorization: Bearer bm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a10-5b2e-4c1d-9a77-0e1f2a3b4c5d" \
  -d '{
    "prompt": "Banner para un café de altura",
    "sizes": ["300x250", "728x90"],
    "locales": ["es-CR", "en-US"]
  }'

Si repites este mismo comando, recibes la misma respuesta con Idempotent-Replayed: true y no se cobra otra vez.