Scannable Docs
Get started

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:

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current minute.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetSeconds 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:

429 response headers
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Wait 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=100 when you page. One request then returns 100 records, not 20.
  • On the items list, send include=data_fields,inspection_frequencies rather than retrieving each item.
  • Slow down when X-RateLimit-Remaining nears 0, rather than waiting for a 429.

A 304 Not Modified counts against the limit like any other response. Sending If-None-Match saves bandwidth, not requests. See Skip unchanged pages.

On this page