Rate limits
How many requests a key may send, the headers that report it, and what to do at the limit.
Each API key may send 60 requests a minute to each endpoint. Listing items and retrieving one item count separately, so a key can send 60 of each in the same minute.
The limit belongs to the key, not to the address it calls from. Two systems sharing a key share its limit, so give each system its own key.
Headers
Every response carries the state of the limit for that endpoint:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current minute. |
X-RateLimit-Remaining | Requests left in the current minute. |
X-RateLimit-Reset | Seconds until the count starts again. |
At the limit
Over the limit, the API returns 429 with code: "rate_limited" and a Retry-After header, in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0Wait at least Retry-After seconds, then retry. Go by Retry-After, not X-RateLimit-Reset: once a key is over the limit, the wait can be longer than the reset. Retrying sooner returns 429 again.
Stay under the limit
- Send
limit=100when you page. One request then returns 100 records, not 20. - On the items list, send
include=data_fields,inspection_frequenciesrather than retrieving each item. - Slow down when
X-RateLimit-Remainingnears 0, rather than waiting for a429.
A 304 Not Modified counts against the limit like any other response. Sending If-None-Match saves bandwidth, not requests. See Skip unchanged pages.