> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/errors.md).

# Errors

Every v1 error has the same shape, a stable machine-readable `code`, and a request id you can quote to support.

## Error envelope

```json
{
  "error": {
    "code": "UNSUPPORTED_TOKEN",
    "message": "toToken FOO is not supported on chain 42161. See GET /v1/tokens for the supported tokens.",
    "requestId": "3f9a2c4e-8b1d-4c57-9e0a-2d6f1b7c9a41"
  }
}
```

| Field             | Description                                                                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.code`      | Stable, machine-readable code — **branch on this**. See [the list below](#error-codes).                                                                                 |
| `error.message`   | Human-readable explanation. For `4xx` errors it says what was wrong with the request; for `5xx` errors it is deliberately generic. Wording can change — don't parse it. |
| `error.requestId` | The id of this request — the same value as the `X-Request-Id` header.                                                                                                   |

The HTTP status code always matches the error (see the table).

## Request ids

**Every** v1 response — success or error — carries an `X-Request-Id` header. Log it alongside your own request logs, and **include it whenever you contact support**: it lets us find the exact request.

You can also send your own `X-Request-Id` header (8–128 characters: letters, digits, `.`, `_`, `-`); Swapper then uses yours, which makes correlating logs across systems easier.

## Error codes

| Code                 | HTTP      | Meaning                                                                                                                                                                                                         | What to do                                                                                                |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR`   | 400       | A parameter is missing or malformed — e.g. `fromAmount` isn't a positive integer string, an address doesn't match the chain, `slippage` is out of range.                                                        | Fix the request; `message` names the parameter.                                                           |
| `INVALID_INTEGRATOR` | 400       | `integrator` is missing on a keyless `/v1/quote`, doesn't exist, or differs from your API key's integrator.                                                                                                     | Pass your `integratorId`, or omit it when you send an API key.                                            |
| `INVALID_FEE`        | 400       | `fee` is malformed, was sent without an API key, or is above your maximum.                                                                                                                                      | See [Integrator Fees](https://docs.swapper.finance/api-v1/integrator-fees.md).                            |
| `UNSUPPORTED_CHAIN`  | 400       | The chain isn't served by v1.                                                                                                                                                                                   | Pick a chain from `GET /v1/chains`.                                                                       |
| `UNSUPPORTED_TOKEN`  | 400 / 404 | The token isn't supported on that chain — `400` on `/v1/quote`, `404` on `/v1/token`.                                                                                                                           | Pick a token from `GET /v1/tokens`.                                                                       |
| `UNAUTHORIZED`       | 401       | Authentication required.                                                                                                                                                                                        | Check how you authenticate — see [Authentication](https://docs.swapper.finance/api-v1/authentication.md). |
| `INVALID_API_KEY`    | 401       | The `x-swapper-api-key` header holds an unknown or revoked key.                                                                                                                                                 | Check the header value; create a new key in the dashboard if it was revoked.                              |
| `FORBIDDEN`          | 403       | You're not allowed to do this.                                                                                                                                                                                  | Don't retry unchanged; contact support if you think it's wrong.                                           |
| `ORIGIN_NOT_ALLOWED` | 403       | A browser request without a key named an `integratorId` whose [allowed origins](https://docs.swapper.finance/api-v1/authentication.md#browser-requests-and-allowed-origins) don't include the request's origin. | Add the origin in the dashboard, or call from your server.                                                |
| `NOT_FOUND`          | 404       | Unknown resource or endpoint — e.g. an address that isn't a Swapper deposit address, or a path under `/v1/` that doesn't exist.                                                                                 | Check the identifiers.                                                                                    |
| `NO_ROUTE_FOUND`     | 404       | No route can serve the quote — pair not supported, amount too low or too high, not enough liquidity, or the best route would lose more than half the value. `message` may add the reason.                       | Try a different amount or token pair, or retry later.                                                     |
| `RATE_LIMITED`       | 429       | You're over a [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md).                                                                                                                                 | Wait `Retry-After` seconds; use an API key for higher limits.                                             |
| `INTERNAL_ERROR`     | 500       | Something went wrong on Swapper's side.                                                                                                                                                                         | Retry with backoff; contact support with the `requestId` if it persists.                                  |
| `UPSTREAM_ERROR`     | 502       | A liquidity source or network is temporarily unavailable.                                                                                                                                                       | Retry shortly, with backoff.                                                                              |

{% hint style="info" %}
`404` alone doesn't tell "no route" from "not found" — branch on `code`.
{% endhint %}

One response comes without the envelope, because it's answered before the API sees the request: a **body that isn't valid JSON** (`400`, HTML). Treat any non-JSON error body by its HTTP status.

## Handling errors

* **Branch on `code`, not on `message`.** Codes are part of the contract: an existing code is never renamed or repurposed. **New codes can be added** within v1 — treat a code you don't recognize by its HTTP status class.
* **Don't retry `4xx` unchanged** (except `429`). Fix the request first.
* **Retry `429`, `500`, `502`, `503` and `504`** with exponential backoff and jitter. For `429`, wait at least `Retry-After` seconds.
* **Server errors never expose internals.** `5xx` messages are generic by design; the `requestId` is what lets us see the details.
