Error format
Every error response has a JSON body with one readable message:
{ "error": "Unknown or revoked API key." }The message is written for people. In code, decide what to do from the HTTP status, not the text.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 200 | Success. | Read data and keep next_since for the next page. |
| 401 | The API key is missing, unknown or revoked. | Check the key. Don't retry with the same key. |
| 404 | The endpoint doesn't exist. | Check the path against the reference. |
| 429 | Too many requests. | Wait for the number of seconds in Retry-After, then retry. |
| 500 | Something failed on our side. | Retry with backoff. |
| 503 | The API isn't enabled on this deployment yet. | Retry later. |
Rate limits
Rate limits aren't fixed yet while the API is in draft. They will be listed here before the API is stable. Build your client to handle 429 now: wait for the number of seconds in the Retry-After header, or back off exponentially when the header is missing.
To stay well inside any limit, page with limit=100 and poll at most once a minute, or use webhooks instead of polling.
Retrying
Retry 429, 500 and 503 with exponential backoff and a little random jitter (for example 1, 2, 4 and 8 seconds). Don't retry 401 or 404; the same request will fail the same way.