Gateway Errors

Our implementation follows the GraphQL-over-HTTP specification, which defines three main request scenarios:

The server might deny requests due to missing authentication, rate limits, invalid JSON, or similar issues. In these cases, it returns an appropriate 4xx or 5xx status code.
For a well-formed GraphQL-over-http request, your Accept header determines:
- For application/json, the server returns a 200 status code.
- For application/graphql-response+json:
  - When errors occur without any data, the server returns the appropriate 4xx or 5xx status code.
  - When the server generates at least a partial response, it returns a 200 status code.

Status Codes

When you send a request with the Accept header value application/graphql-response+json, you receive the following status codes when the server denies your request:

400: Invalid format in GraphQL-over-http request (for example: invalid JSON)
401: Request needs authentication
406: Request has missing or unsupported Accept header
429: Request exceeded rate limit
500: Server encountered an internal error

All GraphQL errors include an error code in extensions. Each code corresponds to a HTTP status code. For request errors (where data is not present), these codes specify the response when the client sends Accept: application/graphql-response+json. When multiple errors occur, the server prioritizes client error 4xx over server error 5xx.

Error codes can be changed with the error code mapping.

Status Code: 400

BAD_REQUEST: Server detected a client error and refused to process the request.
TRUSTED_DOCUMENT_ERROR: System can't load or find the trusted document.
PERSISTED_QUERY_ERROR: Automatic persisted query fails.
PERSISTED_QUERY_NOT_FOUND: System requires an automatic persisted query that doesn't exist.
OPERATION_PARSING_ERROR: Operation parsing fails.
OPERATION_VALIDATION_ERROR: Operation validation fails.
OPERATION_PLANNING_ERROR: Operation planning fails.