> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sodacards.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Make order placement safe to retry.

Placing an order is a money movement, so it must be safe to retry. Send an
`Idempotency-Key` header on `POST /v1/orders` and a retry with the same key never
charges you twice.

```bash theme={null}
curl https://api.sodacards.com/v1/orders \
  -H "X-API-Key: sc_live_your_key_here" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_123", "quantity": 1}'
```

Use a fresh unique key (a UUID) per distinct order, and reuse the same key when
retrying that same order after a network error or timeout.

## How it behaves

* **Same key, same body** → you get the original order back, charged exactly once.
* **Same key, different body** → `422 idempotency_key_reused`. The key is bound to
  its first request; do not reuse a key for a different order.
* **Same key, still processing** → `409 request_in_progress`. The first request has
  not finished; retry after a short delay.
* **No key on a mutating request** → `400 idempotency_key_missing`.

<Tip>
  Store the idempotency key with your order record before you send the request, so a
  crash mid-request still lets you retry with the same key.
</Tip>