> For the complete documentation index, see [llms.txt](https://docs-swap.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-swap.crypto-chief.com/getting-started/errors.md). # Errors ## Errors Every failure comes back in one shape: ```json { "error": "NO_ROUTE", "message": "no route between USDC and XYZ" } ``` Branch on `error`. `message` is written for a human reading a log and may be reworded. Responses to the operations carry an `x-request-id` header (`404` and `405` do not). Send your own `X-Request-Id` with the request, and quote the value when contacting support. A field the request does not define is refused, not ignored: `400 INVALID_REQUEST`, with the parse error in `message`. ### Full list #### Access | Status | Code | What happened | What to do | Charged | | ------ | ---------------------- | ------------------------------------------------------- | -------------------------------------------------------------- | ------- | | `401` | `UNAUTHORIZED` | The key in the path is unknown or the project is frozen | Check the key and the project in the Dashboard | No | | `402` | `INSUFFICIENT_CREDITS` | Your credit balance will not cover the call | Top up | No | | `403` | `DOMAIN_NOT_ALLOWED` | The project's domain whitelist refused the call | Add the domain, or call server-side without `Origin`/`Referer` | No | | `403` | `IP_NOT_ALLOWED` | The project's IP whitelist refused the call | Add the calling IP | No | #### The request | Status | Code | What happened | What to do | Charged | | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------- | | `400` | `INVALID_REQUEST` | Malformed JSON, an unknown field, a wrong type, or an unacceptable value — an unknown `executors` value, a rejected `recipient`, a `fee_bps`/`fee_recipient` problem, a bad `executed_tx_hashes` entry, a `quote_id` that is not a valid id, `/v1/approve/*` on Solana, TON or XRP Ledger | Read `message`; it names the cause. Not fixed by retrying | Yes | | `400` | `NETWORK_NOT_SUPPORTED` | The network code is unknown or the network is not enabled | Check [`/v1/networks`](/api-reference/networks.md) | Yes | | `400` | `TOKEN_NOT_FOUND` | The token is not found in the network | Check [`/v1/tokens`](/api-reference/tokens.md); pass the token by address | Yes | | `400` | `SAME_TOKEN` | Input and output are the same token | — | Yes | | `400` | `AMOUNT_INVALID` | The amount is missing, zero, given in both forms, or does not fit the network's amount type | Send exactly one of `amount_in` / `amount_in_human` | Yes | | `404` | `NOT_FOUND` | No such path | Check the `/v1/...` operation | No | | `405` | `METHOD_NOT_ALLOWED` | The path exists with another method | All Swap API operations are `POST` | No | | `413` | `PAYLOAD_TOO_LARGE` | The body is over 64 KiB | — | No | #### The route | Status | Code | What happened | What to do | Charged | | ------ | ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------- | | `422` | `NO_ROUTE` | No route between the tokens through the supported sources | Another pair, another amount, or fewer filters | Yes | | `422` | `INSUFFICIENT_LIQUIDITY` | The pools cannot cover the amount | A smaller amount | Yes | | `422` | `BALANCE_INSUFFICIENT` | `from_address` cannot cover the input and the network fees | Fund the wallet; on Solana insufficient funds arrive differently — as a `200` with `simulation.status: "not_run"` | Yes | | `422` | `SIMULATION_FAILED` | The swap failed simulation on fresh state | Treat it as "this swap would fail on chain right now"; steps are not issued | Yes | #### Limits | Status | Code | What happened | What to do | Charged | | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------- | | `429` | `RATE_LIMITED` | Your project is over its per-second or per-minute request limit (shared with the RPC Gateway) | Slow down to the limit | No | | `429` | `RATE_LIMITED` | The API was too busy to start the call: more than 64 calls of your project in progress, or 16 non-atomic deals open for the wallet | Retry after about one second | Refunded | #### Availability | Status | Code | What happened | What to do | Charged | | ------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `500` | `INTERNAL` | The call failed on the API's side | Do not retry unchanged; report it with the `x-request-id` | Yes | | `502` | `SWAP_UNAVAILABLE` | The API could not be reached | Retry | Refunded | | `503` | `STATE_STALE` | The network state is stale, or, while continuing a non-atomic deal, your previous swap is not visible on chain yet | Retry later; in a non-atomic deal, pass the swap's hash in `executed_tx_hashes` | Refunded; charged when your continuation caused it | | `503` | `STATE_INCOMPLETE` | The pools of the route are still loading | Retry later | Yes | | `503` | `EXECUTOR_UNAVAILABLE` | An executor or an external route source is unavailable — including one your `executors` filter named while it is off | Retry, or widen the filter | Yes | | `503` | `RPC_UNAVAILABLE` | The network could not be read | Retry later | Refunded; charged when your request caused the failed read | | `503` | `NETWORK_UNAVAILABLE` | The network is enabled but did not start | Pick another network or retry later; [`/v1/networks`](/api-reference/networks.md) shows readiness | Refunded | | `503` | `SWAP_UNAVAILABLE`, `BALANCE_NOT_READY`, `BILLING_UNAVAILABLE`, `SWAP_PRICING_UNAVAILABLE` | Temporarily unavailable, refused before the call ran | Retry later | No | | `504` | `TIMEOUT` | No answer in time (after 15 seconds, at most 20) | Retry | Refunded | ### Retrying A retry fixes the same request on: * `429 RATE_LIMITED`, after about one second; * `503 STATE_STALE`, `STATE_INCOMPLETE`, `EXECUTOR_UNAVAILABLE`, `RPC_UNAVAILABLE`, `NETWORK_UNAVAILABLE`, and the `503` codes refused before the call ran; * `502`, `504`. Use a short backoff. A repeated call duplicates nothing: a repeated build returns fresh transactions, a repeated quote a new price. The one thing to guard against: **never send transactions from two different builds for the same step.** Other `4xx` answers are not fixed by retrying: the request has to change. A `500` is not a temporary failure: report it. {% hint style="warning" %} A retry of `/v1/build` spends another 10,000 credits. Rebuild because a step asked for it, because state went stale, or because a deadline passed — not as a polling mechanism. [Billing](/getting-started/billing.md) has the exact refund rule. {% endhint %} ### Reporting a call Send the `x-request-id` of the response (or the `X-Request-Id` you sent), the operation, and the body. The id is how a specific call is found.