Rate limits

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. 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).

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'

Output

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.
`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.

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.

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.

Get started

Activity API

Assets API

Webhooks

RPC

Troubleshooting

Advanced

Buckets

Headers

Retry-After rules

Stay under the limit

​Buckets

​Headers

​Retry-After rules

​Stay under the limit

Buckets

Headers

Retry-After rules

Stay under the limit