Concepts

Rate limits and quotas

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

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#

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#

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#

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.

Source: content/concepts/rate-limits.md