Skip to main content
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

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

Common cases

A few older lists set no pagination code. See Pagination errors. 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.

Mutation error codes

Support mutations fail only with the codes below, besides the common cases above. Each mutation’s reference page lists the codes it returns, under Errors. These codes are stable: Redo adds new ones but never renames one or changes its status or meaning. A missing or another store’s target id, such as the ticket you update, returns null rather than NOT_FOUND.

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.