Errors

We implement the GraphQL-over-HTTP specification, which roughly differentiates three main cases for a request:

  • A request may be denied by lack of authentication, user being rate-limited, invalid JSON, etc. In that case the server will return the appropriate 4xx or 5xx status code.
  • For a well-formed GraphQL-over-http request, the behavior depends on the Accept header sent by the client:
    • For application/json, the status code will always be 200.
    • For application/graphql-response+json:
      • If a request error is returned (data not being present), the server will return an appropriate 4xx or 5xx status code, based on the GraphQL errors codes defined below
      • Otherwise, at least a partial response could be generated and the status code will always be 200.

A request may be denied for the following reasons:

HTTP Status codeDescription
400Ill-formed GraphQL-over-http request ex: invalid JSON
401Unauthenticated
406Missing or unsupported Accept header
429Rate limited
500Internal server error

The on_gateway_request hook can send an arbitrary 4xx/5xx status code.

All GraphQL errors that may be returned will have an error code in extensions. Each of them is associated with a HTTP status code. Those will be used for request errors (data is not present) if the client sent Accept: application/graphql-response+json. As multiple errors may be present, client error 4xx are preferred over server error 5xx.

Error CodeDescriptionHTTP status code
BAD_REQUESTBad request400
TRUSTED_DOCUMENT_ERRORTrusted document could not be loaded or doesn't exist400
PERSISTED_QUERY_ERRORAutomatic persisted query failed400
PERSISTED_QUERY_NOT_FOUNDAutomatic persisted query was not found and must be provided400
OPERATION_PARSING_ERROROperation parsing failed400
OPERATION_VALIDATION_ERROROperation validation failed400
OPERATION_PLANNING_ERROROperation planning failed400
UNAUTHENTICATEDUser is not authenticated401
UNAUTHORIZEDUser is not authorized403
RATE_LIMITEDRequest was rate limited429
INTERNAL_SERVER_ERRORInternal server error500
HOOK_ERRORHook failed or returned an error500
SUBGRAPH_ERRORGraphQL error coming from the subgraph502
SUBGRAPH_INVALID_RESPONSE_ERRORSubgraph returned an invalid response502
SUBGRAPH_REQUEST_ERRORRequest to the subgraph failed502
GATEWAY_TIMEOUTRequest execeed the global timeout504

Hooks can override the error code by specifying one in the code extension field of the GraphQL error they emit.