API Rate-limit
Rate-limit HTTP headers
Two windows are enforced on every request — a per-second burst and a daily quota — and both are reported on every response, successful or throttled.
Standard fields
The API implements the IETF RateLimit header fields. These are the fields to build your client on:
| Field name | Description |
|---|---|
| RateLimit-Policy | The quotas the API enforces: q requests per w seconds, for each named window. Constant across responses. |
| RateLimit | What is left of each window right now: r requests remaining, t seconds until that window resets. |
RateLimit-Policy: "burst";q=10;w=1, "daily";q=50000;w=86400
RateLimit: "burst";r=7;t=1, "daily";r=49873;t=3421
t is a relative number of seconds, not a timestamp, so it requires no clock synchronisation between your client and our servers.
RateLimit-Policy always lists every enforced window. RateLimit only lists the windows that were actually evaluated for that request: when the burst window is exhausted the daily window is not measured, so it is absent.
Legacy fields
The following headers predate the standard ones and are kept for backward compatibility. They only ever describe one window — the daily one on a success, the exhausted one on a 429:
| Header name | Description |
|---|---|
| X-Rate-Limit-Limit | The maximum number of requests permitted in that window. |
| X-Rate-Limit-Remaining | The number of requests remaining in that window. Always 0 on a 429. |
| X-Rate-Limit-Reset | The time at which that window resets, in UTC epoch seconds. Absent on a 429. |
Prefer RateLimit over these: it is unambiguous about which window it describes.
Handling a 429
Once a window is exhausted the API answers 429 Too Many Requests and adds Retry-After:
| Header name | Description |
|---|---|
| Retry-After | How long to wait before making a follow-up request, as a number of seconds (RFC 9110). Only sent on a 429. |
Retry-After takes precedence over anything you compute from RateLimit. A throttled response looks like this:
HTTP/1.1 429 Too Many Requests
Retry-After: 3421
RateLimit-Policy: "burst";q=10;w=1, "daily";q=50000;w=86400
RateLimit: "burst";r=9;t=1, "daily";r=0;t=3421
X-Rate-Limit-Limit: 50000
X-Rate-Limit-Remaining: 0
Rate-limit tresholds
| Request by | Window time |
|---|---|
| 10 | Requests by second |
| 50 000 | Requests by day |