Idempotency | Respona API

Launching is the only credit-bearing call, so it is protected by idempotency. Every POST /rest/api/v1/orders/{order_id}/launch requires an Idempotency-Key header:

$ curl -X POST https://api.respona.com/rest/api/v1/orders/123/launch \
>   -H "x-api-key: cpk_your_key_here" \
>   -H "Idempotency-Key: 5f3c9a2e-1b7d-4e2a-9c8f-0a1b2c3d4e5f"

Generate a unique key per launch attempt — a UUID is ideal. Reuse the same key when you retry the same launch (after a timeout or network error); use a new key for a genuinely different launch.

Semantics

The key is scoped to your API key and remembered for 24 hours along with a fingerprint of the request body:

You send	Result
Same key + same request	The original response is replayed. No second launch, no second charge.
Same key + different request	`409 Conflict` (`IDEMPOTENCY_CONFLICT`) — the key was already used for a different request.
Same key while the first is still in flight	Requests are serialized so only one launch fires; the duplicate waits and receives the stored result.
New key	Treated as a fresh launch.

This makes retries safe: if you don’t get a response, retry with the same key and you’ll either complete the original launch or receive its stored result — never a double charge.

Other endpoints

Only launch requires an idempotency key. The other writes (create, add placements, remove placement, delete) are guarded by the DRAFT-state requirement and are cheap to retry, so an Idempotency-Key is accepted but not required on them.

Degraded mode

The idempotency store backs the launch guarantee, so launch fails closed: if the store is unavailable, launch returns 503 rather than risk a duplicate charge. Non-launch endpoints are unaffected. See Errors.