> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.respona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.respona.com/_mcp/server.

# Idempotency

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:

```bash
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](/guides/api-conventions/errors).