Idempotency

If a request is cut off by the network, you do not know whether it arrived. With Idempotency-Key you can retry it without generating or charging twice. Use it on the POST requests that create work (create, correct, add sizes and locales, export, upload files); GET queries do not need it.

How it works

• •Send Idempotency-Key with a unique text of up to 200 characters. A UUID works well.
• •Same key and same body: you receive the same response, with the Idempotent-Replayed: true header. Nothing is generated or charged again.
• •Same key and different body: 422 error (idempotency_mismatch).
• •Same key while the first request is still in progress: 409 error (conflict). Wait a moment and retry.
• •Only successful responses are stored: if the request fails, the key is free again.

Example

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 for a high-altitude coffee",
    "sizes": ["300x250", "728x90"],
    "locales": ["es-CR", "en-US"]
  }'

If you repeat this same command, you receive the same response with Idempotent-Replayed: true, and nothing is charged again.