Skip to main content

Error Handling

An API powered by GraphQL differs from typical REST APIs in that it does not rely on HTTP status codes for all different types of errors. GraphQL puts an accent on consistency and predictability and the response from a GraphQL server includes an errors field where all errors are collected.

Query Validation Failed#

Given the following query:

query {  invalidQuery {    id  }}

The following error will be thrown:

400 Bad Request
{  "errors": [    {      "message": "Cannot query field \"invalidQuery\" on type \"Query\".",      "extensions": {        "code": "GRAPHQL_VALIDATION_FAILED"      }    }  ]}

Invalid access token#

In case of an invalid access token, the following error will be thrown:

400 Bad Request
{  "errors": [    {      "message": "Authentication required",      "extensions": {        "code": "UNAUTHENTICATED"      }    }  ]}

No access to object#

Given the following mutation:

mutation {  deleteBuilding(id: "5cd6a93f-372a-4ca6-bb6b-af77b8a7622e") {    success  }}

The following response with an error will be thrown, please note that the deleteBuilding field is returned with a null value and the response code is 200 OK:

200 OK
{  "errors": [    {      "message": "Unauthorized",      "extensions": {        "code": "NOT_AUTHORIZED"      }    }  ],  "data": {    "deleteBuilding": null  }}

Missing required parameter#

Given the following mutation:

mutation {  deleteBuilding {    success  }}

The following error will be thrown:

400 Bad Request
{  "errors": [    {      "message": "Field \"deleteBuilding\" argument \"id\" of type \"String!\" is required, but it was not provided.",      "extensions": {        "code": "GRAPHQL_VALIDATION_FAILED"      }    }  ]}

The response can also contain multiple errors, e.g. when an invalid parameter is used:

mutation {  deleteBuilding(invalidParameter: "invalid") {    success  }}

This results in two errors, one for the required field and one for the invalid parameter:

400 Bad Request
{  "errors": [    {      "message": "Unknown argument \"invalidParameter\" on field \"Mutation.deleteBuilding\".",      "extensions": {        "code": "GRAPHQL_VALIDATION_FAILED"      }    },    {      "message": "Field \"deleteBuilding\" argument \"id\" of type \"String!\" is required, but it was not provided.",      "extensions": {        "code": "GRAPHQL_VALIDATION_FAILED"      }    }  ]}

Too complex queries#

Given the following query:

query {  client {    buildings(first: 2000) {      edges {        node {          name        }      }    }  }}

The following error will be thrown (learn more about query complexity in the section API Rate Limiting):

400 Bad Request
{  "errors": [    {      "message": "Query too complex: 6002. Max allowed complexity: 4000",      "extensions": {        "code": "QUERY_TOO_COMPLEX"      }    }  ]}

Rate limit reached#

This error is thrown when there are too many requests in a short period of time.

400 Bad Request
{  "errors": [    {      "message": "tbd",      "extensions": {        "code": "RATE_LIMIT"      }    }  ]}