# Idempotency (/docs/idempotency)

Every route that buys, refunds or changes something takes an `Idempotency-Key` header. Sending the same request again with the same key never runs it twice: you get the result of the first call. This makes it safe to retry after a timeout or a dropped connection.

## Which routes need it [#which-routes-need-it]

- Placing an order: every product's `POST /v1/<product>/order` and the mixed `POST /v1/orders`.
- After purchase: cancel, update, amendment quote and confirm, manual amendment create and approve (`/v1/order-items/{id}/...`).
- eSIM provisioning, wallet transfers, and resending a traveller email.

Each route in the [API reference](/docs/api-reference) shows whether it takes the header.

## Using a key [#using-a-key]

- Generate a new UUID for each new intent, such as each purchase your customer makes.
- Store it with your own record before you send the request.
- On a timeout, a network error or a `5xx`, send **the same request with the same key and the same body**.
- Use a new key only for a new, intentional operation.

A missing or empty key is `400 / 10001` with `details[0].path` `headers.Idempotency-Key` and reason `REQUIRED`; a value that is not a UUID has the reason `INVALID_VALUE`. Nothing runs in either case.

The key is scoped to your account and to the operation. Rotating your API key, or a repeat sent by another key of the same account, does not create a new order. The same UUID on two different operations does not link them.

## Repeating an order [#repeating-an-order]

| Situation | Response |
|---|---|
| The order was accepted and the request matches | `200` with the same order `id`, as the order reads now |
| The first request is still running | `409 / 12002` `IDEMPOTENCY_KEY_IN_PROGRESS` with `Retry-After` (seconds). Repeat the same request after that delay |
| The body, route or another significant value changed | `409 / 12001` `IDEMPOTENCY_KEY_REQUEST_MISMATCH` |
| The first request's wallet charge was refused (`402 / 16000`) | No order was kept. After a top-up, the same key and body place the order |
| The outcome cannot be determined | `409 / 10005`, `500 / 10000` or `503 / 10011`, and nothing runs again. Check your orders before acting, and give the `requestId` to support |

A completed key never becomes free again: a new purchase needs a new key. A repeat does not retry payment or delivery; it returns the order as it is. A rejected item is refunded automatically, so delivering it again means a new order.

<Callout type="warn" title="A missing response is not a failed order">
A timeout or a `5xx` does not prove that nothing was bought. Repeat with the same key, or read your orders, before buying again with a new key.
</Callout>

## What counts as the same request [#what-counts-as-the-same-request]

- The order of JSON object members does not matter. The order of array elements does.
- Numbers compare by value: `10`, `10.0` and `1e1` are the same; the string `"10"` is not.
- Strings compare exactly, with no trimming or case folding.
- An explicit `currency` is not the same as an omitted one.
- In Sandbox, the `OpenRoam-Sandbox-Scenario` header is part of the request.
- On the mixed `POST /v1/orders`, `maxTotal` is part of the request.

## Repeating other changes [#repeating-other-changes]

| Route | Repeat with the same key and body, once the first call completed |
|---|---|
| Cancel, update, amendment confirm, manual amendment approve, eSIM provisioning, wallet transfer, email resend | `200` with the result of the first call, as it reads now. Nothing runs again: a resend sends no second email |
| Manual amendment create | `409 / 12000` `IDEMPOTENCY_KEY_ALREADY_USED`. Read the request it made with `GET /v1/order-items/{id}/amendments` |
| Amendment quote | `409 / 12000` `IDEMPOTENCY_KEY_ALREADY_USED`. A quote is not kept, so a lost one cannot be read back: request a new quote with a new key |

On every keyed route, a request still running is `409 / 12002` with `Retry-After`, and a changed body is `409 / 12001`.

## Example responses [#example-responses]

```json title="409 Conflict, Retry-After: 2"
{
  "code": 12002,
  "name": "IDEMPOTENCY_KEY_IN_PROGRESS",
  "message": "A request with this idempotency key is in progress. Retry later.",
  "requestId": "b7064e5023c4486587d8162a5ed29f8b"
}
```

```json title="409 Conflict"
{
  "code": 12001,
  "name": "IDEMPOTENCY_KEY_REQUEST_MISMATCH",
  "message": "This idempotency key was used for a different request.",
  "requestId": "b7064e5023c4486587d8162a5ed29f8b"
}
```

Tell outcomes apart by HTTP status and `code`, never by `message`.