> For the complete documentation index, see [llms.txt](https://listed-exchange.gitbook.io/listed/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://listed-exchange.gitbook.io/listed/developers/errors-and-limits.md).

# Errors & limits

## Status codes

\| Status | Where | Meaning | What to do | | --- | --- | --- | | `200` | both | OK. Note `/quote` can return `{ "route": null }` at `200`. | — | | `400` | both | Invalid parameter or malformed JSON body (including a partner fee without a recipient). | Fix the request. The `error` string says what. | | `401` | both | Missing / malformed / revoked API key. | Check the key. Don't retry in a loop. | | `429` | both | The API key exceeded its request budget. | Wait for the response's `Retry-After` seconds, then retry. | | `422` | build | No executable route for this trade right now. | Surface "no route" to the user; optionally retry after a few seconds. | | `502` | both | Upstream venue or RPC failure. | Retry with exponential backoff. | | `503` | both | API not configured, or the key store is briefly unavailable. | Retry with backoff. |

All error bodies are `{ "error": "<message>" }`.

## Validation rules

| Parameter                    | Rule                                                                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `from`, `to`                 | Match `^[A-Za-z0-9._-]{1,24}$`.                                                                                        |
| `amount`                     | A finite number `> 0`. No upper bound is enforced — don't request nonsensical sizes.                                   |
| `slippageBps`                | Integer, `0` ≤ n ≤ `5000`. Non-integers are rejected.                                                                  |
| `fromDecimals`, `toDecimals` | Integer, `0` ≤ n ≤ `36`.                                                                                               |
| `fromAddress`, `toAddress`   | `0x…` hex address, or the literal `native`.                                                                            |
| `sender`                     | `0x…` hex address. Optional on `/quote`, **required** on `/swap/build`.                                                |
| `partnerFeeBps`              | Integer, `0` ≤ n ≤ `50`. Default `0`.                                                                                  |
| `partnerFeeRecipient`        | Valid `0x` address. Required when `partnerFeeBps` > 0.                                                                 |
| `preferEngine` / `engine`    | `kyberswap` / `rialto` / `xpath` / `nordstern` / `de1` / `ekubo`. Anything else is ignored (falls back to best-route). |

## Rate limits

Each active partner API key can make **500 requests per 60-second window**, shared across `/quote`, `/swap/build`, and `/swap/confirm`. A limited request receives `429` and a `Retry-After` response header. This protects the venue and RPC dependencies used to build every quote.

Within that budget:

* Poll `/quote` no faster than the app does — roughly **once every 4 seconds** per active quote.
* Call `/swap/build` once, at signing time — not on a poll.
* Cache nothing that says `no-store` (both endpoints do).
* Back off on `429`, `502`, and `503`.

Abusive traffic can have a key revoked.

## Timeouts

Quote caps server work at **15 seconds**; build and confirmation cap it at **30 seconds**. A cold quote across every venue can take a few seconds; set your client timeout to at least 20 s for quotes and 35 s for builds/confirmations.

## Transport

* Server-to-server only. No CORS headers — a browser `fetch` will be blocked by the browser, not by LISTED.
* HTTPS only.
* Keep your key out of client bundles, logs, and error trackers.