Errors - Redo

The v3 API follows GraphQL error conventions. A response can contain data, errors, or both. Always inspect the errors array, even when the HTTP status is 200.

Error shape

{
  "errors": [
    {
      "message": "Query cost exceeds the rate limit",
      "extensions": { "code": "THROTTLED" }
    }
  ]
}

Machine-readable details live under extensions. Branch on code, not on message.

Common cases

Situation	HTTP status	Code
Missing, malformed, or unknown token, or token for another store	`401`	none (`Unauthorized`)
Token lacks a scope a selected field requires	`403`	`INSUFFICIENT_SCOPE`
Query cost exceeds the points available	`429`	`THROTTLED`
Cursor is empty or invalid	`400`	`INVALID_CURSOR`
`first`/`after` combined with `last`/`before`	`400`	`INVALID_PAGINATION`
Page size outside 1–100	`400`	none
Invalid mutation input	`400`	varies

A record that does not exist is returned as null, not as an error.

Authentication failures are deliberately uniform. A bad header, an unknown token, a nonexistent store, and a token that belongs to another store all return { "errors": [{ "message": "Unauthorized" }] }, so they cannot be told apart.

Handling throttling

When you receive a THROTTLED error, wait the number of seconds given in the Retry-After header before retrying, and consider lowering query cost by requesting smaller pages or fewer fields. See Rate limiting.