> For the complete documentation index, see [llms.txt](https://flowrouter.gitbook.io/flowrouter-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flowrouter.gitbook.io/flowrouter-docs/build-with-flowrouter/swap-api-reference.md). # Swap API errors and limits Error codes and request limits of the FlowRouter Swap API v1. This page completes the [Swap API v1](/flowrouter-docs/build-with-flowrouter/swap-api.md) reference. For how to handle errors and when to retry, see [Errors and retries](/flowrouter-docs/build-with-flowrouter/errors.md). ## Errors Every error from the API has an HTTP status and this body: ```json { "code": "NO_ROUTE", "message": "No executable route is available right now.", "requestId": "6f1c2a8e-0b7d-4c43-9a51-2f0e8d4b7c19" } ``` | HTTP | `code` | Meaning | Action | | ---- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | | 400 | `INVALID_REQUEST` | A parameter is missing, unknown, repeated, empty, or out of range. Or `recipient` differs from `taker`, or the two tokens are the same. | Correct the request. | | 400 | `TOKEN_NOT_SUPPORTED` | A token is not in the current token list. | Check `/tokens`. | | 401 | `UNAUTHORIZED` | An `X-API-Key` header was sent, but the key is wrong, expired, or revoked, or the request has two keys. | Check the header, or send no key. | | 403 | `FORBIDDEN` | The request has an `Origin` header, or the key does not allow this endpoint. | Call from a server. | | 404 | `NOT_FOUND` | Unknown path. | Use a documented endpoint. | | 405 | `METHOD_NOT_ALLOWED` | The method is not `GET`. | Use `GET`. | | 422 | `NO_ROUTE` | No executable route now. | Try again later, or try another amount. | | 422 | `NO_EXECUTABLE_ROUTE` | Routes exist, but each one failed its simulation at the current block. | Try again shortly, or try another amount. | | 422 | `INSUFFICIENT_LIQUIDITY` | The route cannot take the full sell amount. The API never returns a partial fill. | Use a smaller amount. | | 422 | `SIMULATION_FAILED` | The simulation did not succeed, or the quote became stale. | Request a new quote. | | 429 | `RATE_LIMITED` | Your client IP address or your key reached a request limit. The response has `Retry-After` in seconds. | Wait for `Retry-After`. | | 503 | `SERVICE_BUSY` | The service is at its limit. A price or quote can first wait up to 3 seconds for capacity. The response has `Retry-After`. | Wait, then try again. | | 503 | `SERVICE_UNAVAILABLE` | The service cannot quote now. For example, the chain state is stale, execution is paused, or the API could not yet confirm the referral code's settings on chain. Often has `Retry-After`. | Wait, then try again. | | 500 | `INTERNAL` | The service could not validate its own response. | Try again one time. Report the `requestId`. | Some errors do not come from the API and have no JSON body from FlowRouter. Examples are an edge rate limit, a proxy timeout (`502`, `504`), or a CDN error page. Treat a response without the JSON error body as a temporary failure. ## Limits Requests are rate limited. Without a key, the limits apply to each client IP address and to all clients without a key together. Price and quote requests without a key share a small capacity; when it is in use, a new request gets `503 SERVICE_BUSY` at once. When the web app is busy, price and quote requests can also get `SERVICE_BUSY`. When all capacity is in use, a price or quote waits for at most 3 seconds, then gets `503 SERVICE_BUSY`. Invalid requests also count toward the limits. The limits can change. Handle a limit response as follows: 1. On `429 RATE_LIMITED` or `503 SERVICE_BUSY`, read the `Retry-After` header. It gives the wait in seconds. 2. Do not send the request again before that time. 3. Keep parallel price and quote requests within your limits. 4. A `429` with an HTML body comes from the network edge, not from the API. Wait, then send fewer requests. ### Self-serve keys A key from the [API keys page](https://flowrouter.xyz/developers/api-keys/) has these limits: | Requests | Limit for each key | | ----------------- | --------------------- | | Price | 4 per second, burst 8 | | Quote | 2 per second, burst 4 | | Tokens and health | 4 per second, burst 8 | All self-serve keys together also share one capacity. A key over its own limit gets `429 RATE_LIMITED`. When the shared capacity is in use, a request gets `503 SERVICE_BUSY`. Follow the steps above for both. Contact us if your integration needs higher limits. A `/quote` response can take several seconds, plus up to 3 seconds of waiting for capacity. Set your client timeout to at least 20 seconds.