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": "..." }
]
}| Field | Use it for |
|---|---|
code | Choosing how to handle the error |
name | The machine name of the code, such as INVALID_REQUEST. Never localized |
message | A human-readable text. It may be localized: never parse it |
requestId | Give it to support when you report a problem. It is not an order id |
details | Optional. 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
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 10000 | INTERNAL_ERROR | 500 | Save the requestId. For a purchase, check its state first |
| 10001 | INVALID_REQUEST | 400 | Fix the input. details names the field. An unknown query parameter or body member is refused too |
| 10002 | UNAUTHORIZED | 401 | Check the API key and the environment |
| 10003 | FORBIDDEN | 403 | Check the key's permissions and the products enabled for the account (SERVICE_NOT_ENABLED) |
| 10004 | NOT_FOUND | 404 | The id is unknown, or belongs to another account |
| 10005 | CONFLICT | 409 | Read the resource again before acting |
| 10006 | RATE_LIMITED | 429 | Wait for Retry-After when it is present |
| 10007 | TEMPORARILY_UNAVAILABLE | 503 | For a purchase, check its state before retrying |
| 10008 | REQUEST_NOT_COMPLETED | 502 | Save the requestId. It does not confirm that a purchase failed |
| 10009 | RESPONSE_TIMEOUT | 504 | Check the state of the operation |
| 10010 | UNPROCESSABLE_REQUEST | 422 | Check the data and the conditions of the operation |
| 10011 | SERVICE_UNAVAILABLE | 503 | Whether to retry depends on the operation and its state |
| 10012 | METHOD_NOT_ALLOWED | 405 | Check the method and the Allow header |
| 10013 | PAYLOAD_TOO_LARGE | 413 | Send a smaller body |
| 10014 | UNSUPPORTED_MEDIA_TYPE | 415 | Send Content-Type: application/json |
Offers and prices
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 11002 | OFFER_PRICE_CHANGED | 409 | The price rose above inputs.maxPrice or maxTotal, or above the searched price for hotels and flights. Quote again and confirm the new price |
| 11003 | OFFER_UNAVAILABLE | 409 | The offer is no longer sold. Search again |
| 11004 | OFFER_EXPIRED_OR_INVALID | 400 | The publicId expired or is not an offer. Search or quote again |
| 11005 | OFFER_CURRENCY_MISMATCH | 400 | Get an offer in the order currency |
| 11006 | OFFER_TERMS_CHANGED | 409 | The cancellation terms changed. Quote again and confirm the new terms |
Idempotency
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 12000 | IDEMPOTENCY_KEY_ALREADY_USED | 409 | The operation already completed. Read its result; use a new key only for a new operation |
| 12001 | IDEMPOTENCY_KEY_REQUEST_MISMATCH | 409 | The key was used with another request. Restore the original body |
| 12002 | IDEMPOTENCY_KEY_IN_PROGRESS | 409 | Wait Retry-After seconds and repeat the same request |
Payment and wallets
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 16000 | PAYMENT_FAILED | 402 | The 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 |
| 17000 | WALLET_CURRENCY_ALREADY_EXISTS | 400 | You already have a wallet in this currency |
| 17001 | WALLET_LABEL_ALREADY_EXISTS | 400 | Choose another wallet label |
After purchase
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 18000 | CANCELLATION_NOT_SUPPORTED | 422 | This kind of item can never be cancelled once delivered (airtime, utility, gift cards, eSIMs). Do not retry |
| 18001 | CANCELLATION_NOT_AVAILABLE | 409 | Not now: details[0].reason is IN_PROGRESS, MANUAL_REVIEW or NOT_AVAILABLE |
| 18002 | AMENDMENT_NOT_SUPPORTED | 422 | This kind of item cannot be changed |
| 18003 | AMENDMENT_NOT_AVAILABLE | 409 | Not now. MANUAL_REVIEW points to the manual amendment routes |
| 18004 | UPDATE_NOT_SUPPORTED | 422 | This kind of item cannot be updated. Do not retry |
| 18005 | UPDATE_NOT_AVAILABLE | 409 | Not now; same reasons as above |
| 18006 | EMAIL_NOT_SUPPORTED | 422 | The order has no traveller email. Do not retry |
| 18007 | EMAIL_NOT_AVAILABLE | 409 | The 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:
| Code | Name | Where |
|---|---|---|
| 11001 | FULFILLMENT_REJECTED | items[].fulfillment.failure: the item was not delivered. It is refunded automatically |
| 16000 | PAYMENT_FAILED | payment.failure: the payment of a dashboard order failed |
A nested failure is { code, name, message }, with no HTTP status and no requestId.