Status codes
Errors have the shape
{ "error": "message" }. The message is for people: show it or log it, but
decide on the status code, not the text. A 5xx may come without that shape (as plain text, say):
don’t count on its body.
When a request fails (5xx)
A500, 502, 503 or 504 means the request didn’t get through this time; the same request
usually works a moment later. Retry with backoff: wait a second, then two, then four and so on, up
to a minute or so between tries, and give up after a few tries until your next run.
Every request in the API is a GET, so every request is safe to repeat: asking again changes no
data (though it counts against your daily limit), and gives you the same page (or a newer one) for the same values. When
you mirror a channel, ask again with the same cursor or since you used; store next_cursor or
next only after you have applied its page, and a failure never makes you skip one.
Requests per second
Each organization may make 5 requests a second, in bursts of up to 10, across all its keys. A request over that answers429 with Retry-After: 1: wait a second and try again. Paging through
a channel’s offers one page after another stays well within it.
Daily limit
The day is the UTC day: the limit resets at 00:00 UTC. Every request with your key counts against
it, also one that answers
400 or 404 (not one refused for a limit). A request over the limit
isn’t counted and answers 429 with Retry-After, the seconds until 00:00 UTC.
While your plan has a limit, every response carries these headers (all but a 401, and a 429 for
the per-second limit):
To size your requests, see Requests it takes.
Pages and caching
Successful answers may be reused for up to five minutes (
Cache-Control: private, max-age=300).