Handling 429 rate limits

A 429 with error: "rate_limited" means you went over a route’s budget for the current window. Limits are per route, over a rolling 60-second window, and counted per client IP address rather than per key.

That last part surprises people: several keys behind one egress address share a bucket. Splitting work across more API keys does not buy more requests.

Broadly, reads allow 60 requests per 60 seconds and writes allow 10. A few routes carry no route limit at all: the public scope list, the OpenAPI document, and signing out.

Read your budget before you hit the wall

Throttled routes report where you stand on every response, not just on a 429:

Header	Meaning
x-ratelimit-limit	The route’s maximum for the window.
x-ratelimit-remaining	Requests left in the current window.
x-ratelimit-reset	Seconds until the window resets.
retry-after	Seconds to wait. Sent on a 429 only.

Watching x-ratelimit-remaining on successful responses lets a bulk job slow itself down before it starts failing.

Backing off

Honour retry-after when it is present. When it is not, back off exponentially and add jitter, so a fleet of workers that all failed at the same moment does not retry in lockstep. Do not retry in a tight loop. The window is rolling, so a burst of retries keeps the bucket empty and extends the lockout.

Reading 100 items in one request instead of four costs a quarter as much of the same budget, so raise limit before you raise your retry count.

Related

• Rate limits & errors: the per-route numbers.
• Best practices: a retry helper.