Errors
One refusal format across every method, and a request id for support.
The shape
Every refusal looks the same:
{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"details": [{ "field": "limit", "message": "Must be an integer 1…100" }],
"request_id": "9b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
}
}Branch on code, not on the text. message is written for a human and may change; code is part of the contract.
details is not always present. On a validation error it lists the fields, on a missing scope it names the scope, on a rate limit it says which ceiling was hit.
Codes
| HTTP | code | What happened |
|---|---|---|
| 401 | unauthorized | No key, or the key is dead |
| 402 | plan_required | The project's plan does not include the public API |
| 403 | insufficient_scope | The key lacks the required scope |
| 404 | not_found | No such object, or it belongs to another project |
| 409 | conflict | The action contradicts the current state |
| 422 | validation_failed | Bad parameters or body |
| 422 | idempotency_mismatch | The same Idempotency-Key with a different body |
| 429 | rate_limited | Too many requests |
| 500 | internal | Our fault |
An object in someone else's project does not exist, and that is what we answer: 404. There is no separate «forbidden object» — 403 means the key lacks a scope, not that the object is someone else's.
The request id
Every response, successful or not, carries an X-Request-Id header. The same id is inside the error body. Quote it to support and we will find exactly your request.
How to handle them
- 401 and 403 — a configuration problem. Retrying is pointless; fix the key or its scopes.
- 404 — the object is gone. In a sync that is often normal: a record may have been deleted.
- 409 — the state moved. Re-read the object and decide.
- 422 — the request is wrong. Retrying the same body is pointless.
- 429 — wait the number of seconds in
Retry-Afterand repeat. - 500 and timeouts — retry with a growing pause. If it was a write, retry with the same `Idempotency-Key` so you do not create a duplicate.
← Previous: Pagination
Next: Rate limits →