Idempotency
Retry purchases and other changes safely with the Idempotency-Key header.
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
- Placing an order: every product's
POST /v1/<product>/orderand the mixedPOST /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 shows whether it takes the header.
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
| 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.
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.
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.0and1e1are the same; the string"10"is not. - Strings compare exactly, with no trimming or case folding.
- An explicit
currencyis not the same as an omitted one. - In Sandbox, the
OpenRoam-Sandbox-Scenarioheader is part of the request. - On the mixed
POST /v1/orders,maxTotalis part of the request.
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
{
"code": 12002,
"name": "IDEMPOTENCY_KEY_IN_PROGRESS",
"message": "A request with this idempotency key is in progress. Retry later.",
"requestId": "b7064e5023c4486587d8162a5ed29f8b"
}{
"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.