> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> How many requests you can make, and how to back off.

The API limits requests per client in fixed one-minute windows. Anonymous requests are counted per IP address. Requests that carry an API key or a signed-in session are counted per user and per organization, with a larger allowance.

## Allowances

| Requests | Counted per | Allowance per minute |
| - | - | - |
| Anonymous `POST` requests: the [write routes](#counted-routes) | Client IP address | 300 |
| Anonymous reads: the [read routes](#counted-routes) | Client IP address | 300 |
| Requests with a personal API key or a signed-in session, including the capital provider routes | User, and organization | 600 each |
| Requests with an organization API key | Organization | 600, shared with every other credential of the organization |
| Requests to the [counted routes](#counted-routes) whose credential fails authentication | Client IP address | 30 |

The two anonymous allowances are separate: a client that spends its read allowance can still submit, and the reverse.

### How the API identifies a client

An anonymous client is its IP address as Multiliquid's load balancer sees it. `X-Forwarded-For` entries that the caller sends are ignored. An IPv6 client is counted by its `/64` network, so every address in that network shares one allowance. Systems that reach the API through one egress address, such as servers behind a shared NAT gateway, also share one allowance.

### A credential gives a larger allowance

A request that sends an `Authorization` credential, either a customer API key or a signed-in session token, is authenticated before it runs and is not counted against its IP address. It counts instead against 600 requests a minute for its user and 600 a minute for its organization. Every credentialed request from that user or organization shares these two allowances, including requests to the capital provider routes. An organization API key has no user, so its requests count against its organization's allowance alone. If you need more than 300 anonymous requests a minute, use an API key. [Authentication](https://docs.multiliquid.xyz/api-reference/authentication.md#api-keys) explains how to get one.

A key that lacks a route's scope receives `403` with `INSUFFICIENT_SCOPE`. A credentialed `POST /v1/submissions` or `POST /v1/redemptions` with a key that lacks `trade` is rejected this way rather than accepted as an anonymous request.

A supplied credential never falls back to anonymous access. A credential that fails authentication receives `401`, and a valid one without access receives `403`. On the [counted routes](#counted-routes), each `401` for a supplied credential spends one of the client IP address's 30 failed authentications a minute. Once they are spent, every request from that address to a counted route that carries a credential receives `429` before it is authenticated, until the window resets. The capital provider, organization, and delegate routes do not use this allowance.

## Rate-limit headers

Every response to a counted request reports one allowance in three headers, computed when the response is written:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | The requests the allowance permits in each window |
| `RateLimit-Remaining` | The requests it still permits before the window resets |
| `RateLimit-Reset` | The whole seconds until the window resets, rounded up |

```http theme={null}
HTTP/2 200
content-type: application/json
ratelimit-limit: 300
ratelimit-remaining: 287
ratelimit-reset: 41
x-request-id: req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f
```

* The response reports whichever allowance that counted or rejected the request has the fewest requests left, or on a tie the one that resets later.
* An anonymous request is counted by the allowance of its group, reads or writes.
* A credentialed request is counted by its user's allowance once the credential identifies the user, so a `403` or `503` after that point reports the user's allowance. It is counted by its organization's allowance once access is granted. A `401` also spends the client's failed-authentication allowance.
* A credential that is rejected before any allowance counts it reports the client's failed-authentication allowance, which every credential is checked against.
* An allowance whose window has reset by the time the response is written reports all its requests and a full window, which the next request it counts starts.
* Routes that are not counted carry none of these headers. Neither does a request rejected before it is counted, such as one that sends a body with a `GET`.

Browsers can read every header, including these, in cross-origin responses.

## When the allowance is spent

A request over its allowance receives `429` with code `RATE_LIMITED`. `Retry-After` gives the whole seconds until the window resets, and the allowance resets when `Retry-After` elapses. On a counted route `RateLimit-Remaining` is `0`; the capital provider, organization, and delegate routes send no rate-limit headers.

```http theme={null}
HTTP/2 429
content-type: application/json
cache-control: no-store
retry-after: 17
ratelimit-limit: 300
ratelimit-remaining: 0
ratelimit-reset: 17
x-request-id: req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f
```

```json theme={null}
{
  "error": "request rate limit exceeded",
  "status": 429,
  "code": "RATE_LIMITED",
  "details": { "retryAfterSeconds": 17 },
  "requestId": "req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f"
}
```

### A busy service

A `429` whose `RateLimit-Remaining` is above `0` is not a rate-limit rejection, though it has the same code `RATE_LIMITED`: the service is busy. Swap quotes and builds, submissions, redemption preparations, and Solana batch order preparations wait up to 5 seconds for capacity before they answer this way. Redemption intake checks one new redemption at a time, so a redemption that arrives while another is being checked receives this `429` at once. The response still carries `Retry-After`, and its rate-limit headers show the requests the allowance has left.

## Backing off

1. **On `429` with `RateLimit-Remaining: 0`, or without rate-limit headers**, the allowance is spent. Wait the `Retry-After` seconds before sending the request again. Retrying sooner is rejected again and does not shorten the wait.
2. **On `429` with `RateLimit-Remaining` above `0`**, the service is busy rather than the allowance spent. Wait `Retry-After` before retrying.
3. **Pacing**: if you send many requests, read `RateLimit-Remaining` and `RateLimit-Reset`, and wait for the reset when the remaining count reaches zero instead of running into `429`.
4. **On `503`** with `Retry-After`, wait that long. Without `Retry-After`, retry with exponential backoff and jitter, for example after about 1, 2, 4, and 8 seconds, up to a cap. Don't retry a `503` with code `NETWORK_NOT_ACTIVE`: the API does not serve the network.
5. **On `401`**, fix the credential instead of retrying it. On the counted routes, repeated `401` responses spend the failed-authentication allowance and then block every credentialed request from the same IP address to those routes for the rest of the window.
6. **Retries that change state**: resending the same signed transactions to `POST /v1/submissions`, or the same signed redemption to `POST /v1/redemptions`, returns the existing records with `replayed: true`, unless the redemption failed with `failure.resubmittable: true`, which restarts it instead. Resubmitting the same batch order returns `DUPLICATE_ORDER` with its `orderId`, so a retry after a timeout does not submit twice. After a `408` on any other request that changes state, read the current state before retrying. [Retries and idempotency](https://docs.multiliquid.xyz/api-reference/guides/idempotency.md) covers each route.

## Counted routes

Write routes, 300 anonymous requests a minute per client:

* `POST /v1/swap/build`, `POST /v1/swap/decode`, and `POST /v1/submissions`
* `POST /v1/redemptions` and `POST /v1/redemptions/prepare`
* `POST /v1/batch-orders`, `POST /v1/batch-orders/prepare`, `POST /v1/batch-orders/{orderId}/cancel/prepare`, and `POST /v1/batch-orders/{orderId}/cancel`

Read routes, `GET` and `HEAD`, 300 anonymous requests a minute per client:

* `/v1/info`, `/v1/info/evm`, and `/v1/info/svm`
* `/v1/networks` and `/v1/swap/pairs`
* `/v1/transactions` and `/v1/volume`
* `/v1/swap/quote`, `/v1/submissions`, and `/v1/submissions/{submissionId}`
* `/v1/redemptions` and `/v1/redemptions/{redemptionId}`
* `/v1/batch-orders/info`, `/v1/batch-orders`, and `/v1/batch-orders/{orderId}`

`GET /v1/submissions` lists an organization's submissions, so it requires a credential: an anonymous request spends its client's read allowance and then receives `401`.

Health, status, and documentation routes are not counted. The other routes that accept only a credential, the capital provider, organization, and delegate routes, are not counted against the anonymous or failed-authentication allowances and send no rate-limit headers, even on a `401` or `429`. They count against the same 600-a-minute user and organization allowances without reporting them.

## Related

> [card] [Errors](https://docs.multiliquid.xyz/api-reference/guides/errors.md)
>
> The error body and every error code.

> [card] [API introduction](https://docs.multiliquid.xyz/api-reference/introduction.md)
>
> API keys, test networks, and the interactive reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.