All guides
Guide
Errors
Every error from every endpoint has the same shape, and every response carries a request id.
The error body
{
"error": {
"code": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "req_3f9c1a2b4d5e6f708192a3b4c5d6e7f8"
}
}Switch on code. It is one of a fixed list, below. message is written for people and may be reworded, so do not match on it. On a 429 the error also carries retry_after_seconds.
Codes
| code | Status | Meaning | What to do |
|---|---|---|---|
validation_failed | 400 | A parameter or the body is invalid, or a cursor we did not issue. The message names it. | Fix the request. Retrying unchanged will fail again. |
unauthorized | 401 | No key, a key we did not issue, a revoked key, or (on session routes) not signed in. | Send a valid key. |
forbidden_scope | 403 | Your key is valid but not allowed to read this, for example another developer on compliance-export. | Ask us if you think it should have access. |
not_found | 404 | No such resource for you. | Check the id. |
conflict | 409 | Valid, but not possible right now: for example your organisation already holds 20 webhook endpoints. | Remove something you no longer use, then retry. |
rate_limited | 429 | Hourly limit reached, or a daily limit such as 20 new webhook endpoints a day. | Wait Retry-After seconds where given, otherwise try again later. |
quota_exceeded | 429 | Monthly quota used up. | Wait for the 1st, or talk to us about your plan. |
internal_error | 500 | Something failed on our side. | Retry with exponential backoff. Tell us if it persists, quoting the request id. |
We may add codes. If you meet one you do not recognise, act on the HTTP status.
Request ids
Every response, success or error, has an X-Request-Id header. On an error it is the same value as error.request_id. Log it with your own records; if you contact us about a call, quote it and we can find exactly that request.
Not errors
A borough we do not recognise is not an error: /v1/jobs?borough=sowthwark returns an empty list, because values outside London are matched as given. Check spelling before reading an empty result as "nothing here". An unknown type on /v1/jobs also returns an empty list.