Errors

When a GraphQL request fails, the response contains an errors list. Each error has a message, and often an extensions.code you can test in your code. The part of data that failed is null.

Graphql

A request without an API key:

{
  "errors": [
    {
      "message": "Context creation failed: The authorization header is missing.",
      "extensions": { "code": "UNAUTHENTICATED" }
    }
  ]
}

Some errors also come with an HTTP error status: this one is sent with 400 Bad Request. Read the JSON body anyway, it says what went wrong.

A request can also partly succeed: data contains the results that worked and errors lists the rest. Always check errors before using data.

Common causes

Cause	What to check
No key, or an invalid key (UNAUTHENTICATED)	The Authorization: Bearer <key> header, and that the key belongs to this environment (Environments)
An unknown field or argument	The field's name and type in the GraphQL schema. The message often suggests the right name
A variable used but not declared	Declare it in the operation: query Name($id: ID!) { … }
A missing or invalid argument in a mutation	Nothing is run, and the message names the argument. Check its type in the GraphQL schema
A mutation that breaks a rule of the API	Nothing is changed. The message explains the rule and extensions.code gives its name, for example InvalidValueIncludingTaxFailure for a price that doesn't match the tax
No answer after 30 seconds in production	The request is too heavy: ask for smaller pages and fewer nested lists (see Environments)
A page of more than 50 items ("fetching is limited to 50 edges")	Use first: 50 at most: see Pagination