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:

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.

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