# Rate limits and quotas

> The two limits on the data API, how to tell them apart, and how to stay under them.

Page: https://docs.aggre.org/concepts/rate-limits · Section: Concepts · All pages: https://docs.aggre.org/llms.txt

Two independent limits apply to a request. Both answer `429`; they differ by `error.code`.

| | `rate_limited` | `usage_limit_exceeded` |
|---|---|---|
| What is limited | Request rate per source IP | Total requests per key per period |
| Checked | Before the key is looked at | After the key is accepted |
| Header | `Retry-After` (seconds) | none |
| Retry? | Yes, after waiting | No: the quota is spent until the period rolls |

## Rate limit {#rate-limit}

The gateway limits each source IP in process, as a token bucket. The standing configuration is about **20 requests per second with a burst of 40** per IP per gateway pod; because it is applied per pod, the effective ceiling for one IP can be higher when traffic is spread over several pods, and the values are deployment settings that can change. Do not depend on the exact numbers: honour `Retry-After` and back off.

## Quota {#quota}

Each key has a quota and a period (`day`, `month` or `total`). The default for a self-service key is a monthly allowance shown when you create the key. The counter you see in the console and in `GET /v1/whoami` is the current period's count; it can lag a few seconds. A quota applies per key, not per account, so spreading work over several keys raises the total you can use, but an account can hold at most 20 active keys.

## Staying under the limits {#staying-under}

- Use `limit` close to the maximum a route allows instead of many small pages.
- Cache what does not change: instruments and series catalogues, statute text (compare `content_hash` or `updated_since` before re-reading).
- Use change feeds (`updated_since`) rather than re-reading whole datasets.
- Retry `429 rate_limited` with exponential backoff and jitter, and obey `Retry-After`.
- Check `GET /v1/whoami` to see how much of the period a key has used.