13 problem types the API can return
Error catalogue
Every error is RFC 9457 problem+json, and its type is a link to one of the 13 pages below. Branch on type, never on detail or on the status alone, because several codes share a status.
For the shape of a problem body and for retry rules, see errors and retries.
The codes
| code | status | when you see it |
|---|---|---|
| account_too_large | 422 | The account holds more rows than the API will walk in one request (20,000 per table). |
| conflict | 409 | An Idempotency-Key was reused with a different body, or a request with that key is still in flight. |
| duplicate_id | 409 | You supplied an id on create and a row with it already exists. |
| forbidden_scope | 403 | The credential is valid but was not granted the scope this route needs. |
| grant_expired | 401 | The grant reached its expiry. Personal access tokens expire after at most a year; OAuth grants need re-approval after 365 days. |
| grant_revoked | 401 | The grant behind this credential was disconnected. The user did it in Settings, or changed their password, or changed their encryption key. |
| internal | 500 | Something failed on the server that was not your request’s fault. |
| not_found | 404 | No row with that id belongs to this user, or it was permanently deleted. |
| payload_too_large | 413 | The request body is over 1 MB. |
| rate_limited | 429 | A rate bucket is exhausted. |
| unauthorized | 401 | The Authorization header is missing, malformed, expired, or names a credential this server does not know. |
| unsupported_media_type | 415 | The request has no Content-Type: application/json. |
| validation_failed | 422 | A field is missing, the wrong type, too long, or not recognised. Unknown fields are rejected rather than ignored. |