Skip to main content

Rate limits

Each API key has its own rate limit. Limits are enforced at the edge, before a request reaches any product, so throttling never consumes product capacity or counts as billable usage.

How limits work​

A key's limit is a token bucket: it has a steady refill rate (tokens per second) and a burst capacity (the most tokens it can hold at once). Each request spends one token. A short spike can draw down the burst; sustained traffic is held to the refill rate. Buckets refill continuously, so capacity returns gradually rather than resetting on a fixed clock.

The specific rate and burst come from the key's plan and are visible in the console.

When you are throttled​

A request that finds the bucket empty is rejected with 429 Too Many Requests and a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "rate limit exceeded" } }
  • Retry-After is a whole number of seconds to wait before retrying. It is always at least 1.
  • A 429 is transient — the request was not processed and was not metered.

Handling 429​

  1. Respect Retry-After. Wait at least the indicated number of seconds before retrying the request.
  2. Back off exponentially with jitter if you hit repeated 429s, so many clients don't retry in lockstep.
  3. Smooth your traffic where you can — spreading requests over time keeps you under the refill rate instead of exhausting the burst and stalling.

The same Retry-After convention applies to any future endpoint; see Errors for the full list of status codes.