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

# Rate limits and headers

> The limits every key and connection meets, and the headers that report them.

The limits exist to stop runaway clients, not to ration normal use. They sit far above what a working integration needs. If you meet one, your client is most likely looping or leaking connections.

## Limits

| Limit | Value | When you meet it |
| - | - | - |
| Requests per API key | 12,000 per minute | `429 RATE_LIMITED` with `Retry-After` |
| Requests per IP address | 60,000 per minute | `429 RATE_LIMITED` with `Retry-After` |
| Open stream connections per API key | 100 | `429 RATE_LIMITED` on the handshake, with `Retry-After` |
| Subscriptions per stream connection | 100 | An `error` frame refusing the subscribe |
| Unsent frames per stream connection | 1,024 | The server closes the socket with code `4008` |
| Trades per page | 100 | Larger `limit` values are lowered to 100 |
| Candles per request | 5,000 | `countBack` above 5,000 returns `400 VALIDATION_ERROR` |
| Addresses per `spot.tokens` subscription | 100 | An `error` frame refusing the subscribe |

Every key, evaluation or production, has the same limits.

### How the request budget refills

A key's budget refills evenly over each minute, and a full minute's budget can be spent at once. A backfill can therefore burst, then settle to the steady rate.

The IP limit sits above the key limit, so a fleet of your servers behind one outbound IP still gets its full key budget.

### Approximate by design

Limits are counted per server, not across the whole fleet. Treat the numbers as ceilings to stay well under, not as exact quotas to run at.

## Response headers

| Header | On | Meaning |
| - | - | - |
| `X-Request-ID` | Every response | The request's trace ID. Echoes yours, or a generated UUID. See [Request IDs](/concepts/errors#request-ids). |
| `X-RateLimit-Remaining` | Every `/v1` response, refusals included | Requests left in the current window |
| `Retry-After` | Every `429` | Whole seconds to wait before retrying. Never `0`. |

Once your key is accepted, `X-RateLimit-Remaining` reports your key's budget. A response that ends before that point reports your IP address's budget instead: a `401`, a `429` from the IP limit, or a `503` when the key could not be checked.

Pace your client on `X-RateLimit-Remaining` to slow down before you reach the limit.

## Stream connections

A connection counts against your key from its handshake until it closes. Requests over the socket do not spend your request budget.

When your key holds 100 open connections, the next handshake gets:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "This key holds the most open connections it may. Close one and reconnect."
  }
}
```

Waiting alone does not free a slot. Close a connection you no longer need. A single connection holds up to 100 subscriptions, so most integrations need only a few.

## The OpenAPI document

`GET /openapi.json` needs no key, spends no budget, and carries no `X-RateLimit-Remaining` header.


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