Errors

When a request fails, the response has an errors list. Each error has a message written to be read by a person and a code in extensions for your program to act on.

{
  "errors": [
    {
      "message": "This API key does not have the read:staff permission",
      "path": ["site", "orders"],
      "extensions": { "code": "FORBIDDEN" }
    }
  ],
  "data": null
}

Check the body for errors whatever the HTTP status, because a response can be 200 and still carry one. Have your code branch on extensions.code. The wording of message may change.

Codes

Code	HTTP status	Meaning	What to do
`UNAUTHENTICATED`	401	The API key is missing, wrong or revoked	Check the `Authorization` header and the key
`FORBIDDEN`	403	The key cannot read that site, or lacks a permission	Check the key's sites and permissions
`BAD_USER_INPUT`	400	An argument is wrong, such as a bad date or a range that is too long	Fix the request. The message says what is wrong
`GRAPHQL_VALIDATION_FAILED`	400	The query asks for a field that does not exist	Check the query against the reference
`GRAPHQL_PARSE_FAILED`	400	The query is not valid GraphQL	Check the query's syntax
`QUERY_TOO_LARGE`	400	One request asks for too much at once	Split it into smaller requests
`RATE_LIMITED`	429	Too many requests in a short time	Wait, then try again. See limits
`UNAVAILABLE`	503	The service is temporarily unavailable	Try again shortly
`INTERNAL_SERVER_ERROR`	200	Something went wrong on our side	Try again. If it keeps happening, contact support

Examples

A missing or wrong key:

{
  "errors": [
    {
      "message": "Invalid or missing API key",
      "path": ["sites"],
      "extensions": { "code": "UNAUTHENTICATED" }
    }
  ],
  "data": null
}

A site the key does not cover:

{
  "errors": [
    {
      "message": "This API key cannot read that site",
      "path": ["site"],
      "extensions": { "code": "FORBIDDEN" }
    }
  ],
  "data": null
}

A date range that is too long:

{
  "errors": [
    {
      "message": "Range too long - request 92 days or less at a time",
      "path": ["site", "orders"],
      "extensions": { "code": "BAD_USER_INPUT" }
    }
  ],
  "data": null
}

A query that names a field that does not exist. GraphQL suggests the nearest match:

{
  "errors": [
    {
      "message": "Cannot query field \"nope\" on type \"Site\". Did you mean \"name\"?",
      "extensions": { "code": "GRAPHQL_VALIDATION_FAILED" }
    }
  ]
}

Too many requests:

{
  "errors": [
    {
      "message": "Too many requests - slow down and try again shortly",
      "extensions": { "code": "RATE_LIMITED" }
    }
  ]
}

Retrying

RATE_LIMITED, UNAVAILABLE and INTERNAL_SERVER_ERROR are worth retrying. Wait a little longer after each attempt, for example 1, 2, 4 then 8 seconds, and give up after a few tries.

The other codes mean the request itself needs changing, and sending it again will fail the same way.

Since every request is a read, a retry cannot do any harm.

Codes​

Examples​

Retrying​

Codes

Examples

Retrying