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

# Rate limits

> Request buckets per plan, RateLimit headers and Retry-After rules.

Lumeus limits how many requests your organization makes per minute. Limits are
counted per organization, not per key, so more keys or more processes do not add
capacity. This page lists the buckets, the headers that report them and how
long to wait after a `429` or `503`.

## Buckets

| Bucket | Counts | Free | Paid plans |
| - | - | - | - |
| Data | Activity and Assets requests with API keys, together, on both networks | 60 per minute | Plan rate (Starter 600, Growth 3,000, Scale 6,000) |
| RPC | RPC calls; each call in a batch counts as one request | 30 per minute | Plan RPC rate (Starter 300, Growth 600, Scale 1,200) |
| Dashboard | Activity and Assets calls made by the signed-in dashboard | At least 120 per minute | At least the plan rate |
| Browser key | Each publishable key, per end-user IP | Key setting, default 60 per minute | Same |
| Webhooks management | Read, write, safety and test calls, each in its own lane per organization | Per lane | Same |
| Testnet daily cap | Testnet Activity, Assets and RPC requests per UTC day; each call in an RPC batch counts | 10,000 per day | 10,000 per day (Enterprise: unlimited) |

The live plan rates are `rate_per_minute` and `rpc_rate_per_minute` in
[`GET /v1/plans`](/guides/billing#the-plan-catalog). The dashboard bucket is
separate, so busy keys cannot lock you out of the dashboard and the dashboard
does not spend your keys' budget. Webhook test deliveries are also capped at 12
per organization per hour.

## Headers

Rate-limited responses carry the IETF draft headers:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | Requests per minute of the bucket that answered |
| `RateLimit-Remaining` | Whole requests left in the bucket |
| `RateLimit-Reset` | Seconds until the bucket is full again |
| `Retry-After` | On `429` (and `503`): seconds to wait before the next attempt |

Browsers on an allowed origin can read them, on errors too: they are listed in
`Access-Control-Expose-Headers` (see [browser keys](/guides/browser-keys.md#cors)).

```bash theme={null}
curl --fail-with-body --silent --output /dev/null --dump-header - \
  -G "$ASSETS_URL/accounts/$ACCOUNT/holdings" --data-urlencode limit=1 \
  -H "Authorization: Bearer $LUMEUS_API_KEY" | grep -i '^ratelimit'
```

```text Output theme={null}
ratelimit-limit: 60
ratelimit-remaining: 59
ratelimit-reset: 1
```

A batch of two RPC calls lowers `RateLimit-Remaining` by two.

## Retry-After rules

| Response | `Retry-After` | What to do |
| - | - | - |
| `429 rate_limited` (bucket empty) | Seconds until the next request fits the bucket | Wait, then retry. A refused request uses nothing, so the first retry succeeds unless other traffic on the same organization used the refill. |
| `429 rate_limited`, daily Testnet request cap | Seconds until 00:00 UTC (up to 86,400) | Wait for the reset, or use Mainnet. The message says `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`. See [Testnet is free](/guides/limits.md#testnet-is-free). |
| `429` RPC concurrency limit | `1` | Retry after a second; the call did not run. |
| `429` publishable key credit cap | Seconds until the next billing period | Raise or remove `monthly_credit_cap`, or wait. |
| `429` Assets snapshot jobs | `60` | Wait for one of your jobs to finish. |
| `503 busy` | `2` | Retry the same request. |
| `503 query_timeout` | `30` | Narrow the range or lower `limit` before retrying. |
| `503 index_not_ready` | `2` to `60` | Retry later; the data is not readable yet. |
| `503 topic_coverage` | `60` | Use a range inside the stated coverage, or wait. |
| `503` Assets snapshot queue full | `300` | Retry later. |
| `503` from `/readyz` | `5` | Back off; see [health checks](/guides/readiness.md). |

Every Activity and Assets `503` carries `Retry-After`. On other products, honor
it when present and otherwise back off exponentially. Add jitter when many
workers share an organization, and cap your attempts: see the
[retry policy](/guides/errors.md#retry-policy).

## Stay under the limit

* Run a few workers per organization, not one per key. About 8 concurrent
  requests is a good ceiling for heavy history walks.
* Use larger pages (`limit` up to 1,000 on account activity) instead of more
  requests.
* Batch RPC reads only to save round trips; a batch does not save rate.
* Watch `RateLimit-Remaining` and slow down before it reaches zero.


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