Errors

The API uses standard HTTP status codes. Errors return a JSON body with an errors array, so one parser handles every failure.

{
  "errors": [
    { "message": "Missing scope requests:read", "code": "E_AUTHORIZATION_FAILURE" }
  ]
}

Field	Present	Meaning
`message`	Always	A human-readable explanation. Do not parse it.
`code`	Most errors	A stable identifier such as `E_ROW_NOT_FOUND`. Branch on this.
`field`	Validation errors	The input that failed, such as `perPage`.
`rule`	Validation errors	The rule that failed, such as `max`.

Status codes

Status	Code	When
`400`		The request body is not valid JSON.
`401`	`E_UNAUTHORIZED_ACCESS`	The key is missing, invalid, expired or revoked.
`403`	`E_AUTHORIZATION_FAILURE`	The key lacks the required scope, its owner lost access, or its client is not approved.
`404`	`E_ROW_NOT_FOUND`	The resource does not exist, or belongs to another owner.
`409`	`E_REFERENCED`	The resource is still referenced by something else and cannot be deleted.
`422`	`E_VALIDATION_ERROR`	A query parameter or body field failed validation.
`429`	`E_TOO_MANY_REQUESTS`	The key exceeded its rate limit.
`5xx`		A server problem. Retry with backoff.

One error uses a flat shape

409 E_REFERENCED is returned as { "message": "...", "code": "E_REFERENCED" } without the errors array. Handle both shapes if you delete resources.

Validation errors

A 422 lists every invalid field in one response:

{
  "errors": [
    { "message": "The perPage field must not be greater than 100", "rule": "max", "field": "perPage" },
    { "message": "The page field must be at least 1", "rule": "min", "field": "page" }
  ]
}

Handling errors

Fix 4xx errors in your request. Do not retry them unchanged, except 429.
Retry 429 and 5xx with exponential backoff and jitter.
Log the code and your request details, but never log the key.

Status codesCopy Anchor Link

Validation errorsCopy Anchor Link

Handling errorsCopy Anchor Link

On this page

Status codes

Validation errors

Handling errors