Skip to Content
OpenRoam Docs

Errors

The error body, the shared error codes and how to handle each one.

Every error response has the same JSON body. The HTTP status and the application code are different values: a missing key is HTTP 401 with code 10002.

{
  "code": 10001,
  "name": "INVALID_REQUEST",
  "message": "The request is invalid.",
  "requestId": "0123456789abcdef0123456789abcdef",
  "details": [
    { "path": "items[0].inputs.phoneNumber", "reason": "REQUIRED", "message": "..." }
  ]
}
FieldUse it for
codeChoosing how to handle the error
nameThe machine name of the code, such as INVALID_REQUEST. Never localized
messageA human-readable text. It may be localized: never parse it
requestIdGive it to support when you report a problem. It is not an order id
detailsOptional. Each entry is { path, reason, message? }: the field at fault and a machine-readable reason, such as REQUIRED, INVALID_VALUE, UNSUPPORTED_FIELD, NOT_ALLOWED, NOT_SUPPORTED or CURRENCY_MISMATCH

Treat a code you do not know as a general error for its HTTP status, and log the requestId.

Purchases and server errors

A 5xx or a timeout does not prove that a purchase did not happen. Before buying again, repeat the request with the same Idempotency-Key or read the order. See Idempotency.

Request errors

CodeNameHTTPWhat to do
10000INTERNAL_ERROR500Save the requestId. For a purchase, check its state first
10001INVALID_REQUEST400Fix the input. details names the field. An unknown query parameter or body member is refused too
10002UNAUTHORIZED401Check the API key and the environment
10003FORBIDDEN403Check the key's permissions and the products enabled for the account (SERVICE_NOT_ENABLED)
10004NOT_FOUND404The id is unknown, or belongs to another account
10005CONFLICT409Read the resource again before acting
10006RATE_LIMITED429Wait for Retry-After when it is present
10007TEMPORARILY_UNAVAILABLE503For a purchase, check its state before retrying
10008REQUEST_NOT_COMPLETED502Save the requestId. It does not confirm that a purchase failed
10009RESPONSE_TIMEOUT504Check the state of the operation
10010UNPROCESSABLE_REQUEST422Check the data and the conditions of the operation
10011SERVICE_UNAVAILABLE503Whether to retry depends on the operation and its state
10012METHOD_NOT_ALLOWED405Check the method and the Allow header
10013PAYLOAD_TOO_LARGE413Send a smaller body
10014UNSUPPORTED_MEDIA_TYPE415Send Content-Type: application/json

Offers and prices

CodeNameHTTPWhat to do
11002OFFER_PRICE_CHANGED409The price rose above inputs.maxPrice or maxTotal, or above the searched price for hotels and flights. Quote again and confirm the new price
11003OFFER_UNAVAILABLE409The offer is no longer sold. Search again
11004OFFER_EXPIRED_OR_INVALID400The publicId expired or is not an offer. Search or quote again
11005OFFER_CURRENCY_MISMATCH400Get an offer in the order currency
11006OFFER_TERMS_CHANGED409The cancellation terms changed. Quote again and confirm the new terms

Idempotency

CodeNameHTTPWhat to do
12000IDEMPOTENCY_KEY_ALREADY_USED409The operation already completed. Read its result; use a new key only for a new operation
12001IDEMPOTENCY_KEY_REQUEST_MISMATCH409The key was used with another request. Restore the original body
12002IDEMPOTENCY_KEY_IN_PROGRESS409Wait Retry-After seconds and repeat the same request

Payment and wallets

CodeNameHTTPWhat to do
16000PAYMENT_FAILED402The wallet charge was refused and nothing was created. details[0] names wallet with INSUFFICIENT_BALANCE or WALLET_BLOCKED when known. Top up, then repeat with the same Idempotency-Key
17000WALLET_CURRENCY_ALREADY_EXISTS400You already have a wallet in this currency
17001WALLET_LABEL_ALREADY_EXISTS400Choose another wallet label

After purchase

CodeNameHTTPWhat to do
18000CANCELLATION_NOT_SUPPORTED422This kind of item can never be cancelled once delivered (airtime, utility, gift cards, eSIMs). Do not retry
18001CANCELLATION_NOT_AVAILABLE409Not now: details[0].reason is IN_PROGRESS, MANUAL_REVIEW or NOT_AVAILABLE
18002AMENDMENT_NOT_SUPPORTED422This kind of item cannot be changed
18003AMENDMENT_NOT_AVAILABLE409Not now. MANUAL_REVIEW points to the manual amendment routes
18004UPDATE_NOT_SUPPORTED422This kind of item cannot be updated. Do not retry
18005UPDATE_NOT_AVAILABLE409Not now; same reasons as above
18006EMAIL_NOT_SUPPORTED422The order has no traveller email. Do not retry
18007EMAIL_NOT_AVAILABLE409The email cannot be sent as the order reads now; details[0].reason says why

Read an item's actions before you call these routes: each action states its availability and reason. See Orders.

Product codes

Some products add their own codes, such as 20000 AIRTIME_OPERATOR_CHANGED (search again) and 22000 ESIM_SMS_NOT_SUPPORTED (do not retry). Hotels have a range of their own codes. Each product guide lists the codes to handle.

Failures inside a successful response

An order read can answer 200 and still report a failure inside it. These are not HTTP errors:

CodeNameWhere
11001FULFILLMENT_REJECTEDitems[].fulfillment.failure: the item was not delivered. It is refunded automatically
16000PAYMENT_FAILEDpayment.failure: the payment of a dashboard order failed

A nested failure is { code, name, message }, with no HTTP status and no requestId.

On this page