GraphQL API Errors

Introduction

The GraphQL API returns an error response when the requested operation fails to execute successfully. Hasura provides the error responses that adhere to the GraphQL spec. Each error object contains only the message field, providing a string description of the error intended for the API consumer.

note

Note that in future iterations, the error object could be expanded with additional information, such as path and error code.

Below is an example of an error response triggered by using a negative value as the limit argument:

{
  "data": null,
  "errors": [
    {
      "message": "Unexpected value: expecting NON-NEGATIVE 32-bit INT, but found: -10"
    }
  ]
}

Error status code

GraphQL API errors will always be returned with a 200 OK status code. The status code is not indicative of the success or failure of the operation. The errors array in the response object should be checked to determine the success or failure of the operation. Most GraphQL clients will automatically handle this for you.

Internal Errors

Internal errors are unexpected exceptions within the API execution cycle. These often originate from system-level issues such as database inconsistencies or network disruptions which lie beyond the control and scope of the endpoint API consumer.

GraphQL API responses for internal errors do not contain detailed error messages, as API consumers lack, and should not have, the necessary context to resolve such issues. Internal errors may contain sensitive details not meant to be exposed due to privacy and security concerns. Therefore, the API response for internal errors is simplified to only include the message internal error.

Example:

{
  "data": null,
  "errors": [
    {
      "message": "internal error"
    }
  ]
}

However as a Hasura supergraph author, you have access to details of most internal errors, including but not limited to:

• DDN metadata errors:
  • Such as the absence of a data source for model or command root fields or arguments.
  • The omission of required session variables in the request.
• Data connector interactions:
  • These are useful in debugging connection or interface errors with your custom data connectors.

The details are available through traces. It is recommended to review all error spans within the trace to obtain details of the internal error.

If the trace still does not reveal the details of the error, it may originate from Hasura internals. In such cases, please reach out to Hasura support with the trace ID.