Skip to Content
OpenRoam Docs

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>/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 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

SituationResponse
The order was accepted and the request matches200 with the same order id, as the order reads now
The first request is still running409 / 12002 IDEMPOTENCY_KEY_IN_PROGRESS with Retry-After (seconds). Repeat the same request after that delay
The body, route or another significant value changed409 / 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 determined409 / 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.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

RouteRepeat with the same key and body, once the first call completed
Cancel, update, amendment confirm, manual amendment approve, eSIM provisioning, wallet transfer, email resend200 with the result of the first call, as it reads now. Nothing runs again: a resend sends no second email
Manual amendment create409 / 12000 IDEMPOTENCY_KEY_ALREADY_USED. Read the request it made with GET /v1/order-items/{id}/amendments
Amendment quote409 / 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

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"
}
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.

On this page