# Errors (/docs/errors)

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`.

```json
{
  "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`.

<Callout type="warn" title="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](/docs/idempotency).
</Callout>

## Request errors [#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 [#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 [#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 [#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 [#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](/docs/orders).

## Product codes [#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](/docs/products/esims) lists the codes to handle.

## Failures inside a successful response [#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`.