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

# Rate limits

> Requests per second, requests open at once, and the per-address limits in front of the API.

## Per key

| Limit | Pay-as-you-go | Standard | Custom |
| - | - | - | - |
| Requests per second | 1 | 10 | per plan |
| Requests open at once, per chain | 1 | up to 4 | per plan |

* **Requests per second** count all chains together: 10 rps on Standard is 10 per second in
  total, not per chain.
* **Requests open at once** is per chain: a request counts from when it's accepted until its
  response has been **fully read**. On pay-as-you-go it's 1: finish reading one response before
  you send the next query to the same chain. On other plans it's twice the requests-per-second
  limit, but at most 4 per chain for now, so that no single key can take all of a chain's query
  capacity.
* Every accepted response carries `X-RateLimit-Limit` (your requests per second) and
  `X-RateLimit-Remaining` (left in the current second).

Over a limit:

| Status | Code | Meaning | What to do |
| - | - | - | - |
| `429` | `rate_limited` | more requests this second than the limit | wait `Retry-After` (1 s) and retry |
| `429` | `too_many_in_flight` | too many of your requests still open on this chain | finish reading a response, then retry |
| `429` | `key_blocked` | the key kept sending about 10× its limit or more | every request is refused for 5 minutes, on every chain; wait `Retry-After` seconds |

Refused requests are free.

> [!WARNING]
>
> Honor `Retry-After` on every `429`. A client that retries immediately in a tight loop turns
> `rate_limited` into `key_blocked`, which stops the key for 5 minutes on every chain.

## Per client address

In front of the key checks, every route has limits per client IP address, keys or not:

| Status | Code | When |
| - | - | - |
| `429` | `ip_rate_limited` | more than 100 requests per second from one address (`Retry-After: 1`) |
| `429` | `ip_blocked` | the address kept going past that limit, or sent more than 30 requests with a missing or unknown key within a minute; refused for 10 minutes |

Normal clients never meet these. They exist to stop floods and key guessing.

## Busy servers

When a chain's server is at capacity, a request waits up to 5 seconds for a free slot, then gets
`503 unavailable` with `Retry-After: 1`. Retry with backoff. If you see it often, contact us.

## Making the most of your limit

* **Large pages.** Leave `maxObjects` at 100,000. One request then carries up to 100,000 rows; a
  rate of 1 per second still moves a lot of data.
* **Read responses promptly.** A response you're slow to read keeps one of your open-request slots
  busy.
* **Don't poll faster than blocks arrive.** See [Following the head](https://docs.bloklake.com/guides/follow-the-head.md).
* **Serialize per key.** With pay-as-you-go's 1 request per second, run one query at a time per
  key. A simple client-side limiter (one request per second, sequential) never sees a `429`.
* **Need more?** Standard has 10 per second; custom plans can have more.

## Checking your limits

[`GET /v1/account`](https://docs.bloklake.com/api-reference/account) returns the key's `rps` and status. It's free and
doesn't count toward the limit.


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