Error Reference

All error responses use a consistent JSON envelope. Check the HTTP status code and the error.code field to identify the problem programmatically.

Error envelope

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API token."
  }
}

Status	error.code	When it occurs
`400 Bad Request`	`BAD_REQUEST`	A query parameter or request body field has an invalid type or value.
`401 Unauthorized`	`UNAUTHORIZED`	The Authorization header is absent, malformed, or the token does not exist.
`403 Forbidden`	`FORBIDDEN`	The account is suspended or blocked.
`403 Forbidden`	`SCOPE_REQUIRED`	The token is valid but lacks the scope required by this endpoint.
`404 Not Found`	`NOT_FOUND`	The resource ID in the URL does not match any record.
`429 Too Many Requests`	`RATE_LIMIT_EXCEEDED`	Per-minute or monthly quota exceeded. Check the Retry-After header.
`500 Internal Server Error`	`INTERNAL_ERROR`	An unexpected error occurred on our side. Retry with back-off; contact support if it persists.

Missing token (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API token."
  }
}

Missing scope (403)

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This endpoint requires the qualifications:read scope."
  }
}

Rate limit exceeded (429)

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Quota exhausted (429)

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly request quota exhausted. Purchase credits or upgrade your plan."
  }
}

Not found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found."
  }
}