Error responses

The section describes how the Fauna GraphQL API reports errors for GraphQL query requests.

Error types per endpoint

The following table lists the individual HTTP endpoints available in the GraphQL API and the kinds of error responses that your client code should handle where necessary:

Endpoint Description and error responses

POST /graphql

This endpoint executes GraphQL queries.

GraphQL queries can fail for several different reasons:

  • Syntax errors: When a query is malformed in some fashion.

  • Validation errors: When a query involves a type field, or type, that is not specified in the active schema.

  • Resolver errors: When a query involves a resolver, and that resolver encounters a problem, either in the resolver’s logic, in the data that the resolver is attempting to process, or the FQL schema that supports the GraphQL schema.

  • Permission errors: The bearer token/secret provided alongside a query may not be valid, or there may be an Attribute-based access control (ABAC) role that denies permissions required by a query.

For all of these kinds of errors, the GraphQL API returns an HTTP 200 status code, and the error details are in the errors field of the JSON response body. See Example validation error.

GET /ping

An endpoint that can be used to indicate whether the GraphQL API is responding.

This endpoint can return various HTTP errors.

POST /import

An endpoint used to import a GraphQL schema.

This endpoint can return various HTTP errors.

Example validation error

Here is an example validation error response:

{
  hero {
    name
    friends {
      name
    }
  }
}
{
  "data": null,
  "errors": [
    {
      "message": "Cannot query field 'hero' on type 'Query'. (line 2, column 3):\n  hero {\n  ^",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ]
    }
  ]
}

HTTP errors

When HTTP communication with the endpoints listed above fails for any reason, the following kinds of HTTP responses can occur:

Response Description

HTTP 400: Bad Request

The GraphQL API could not understand the request due to invalid HTTP request syntax.

HTTP 401: Unauthorized

The request is not authorized, likely because the required bearer token is missing.

HTTP 403: Forbidden

The bearer token provided in the request is not authorized to execute the provided query.

HTTP 409: Conflict

The query could not provide a response before a query limit (e.g. transaction size, transaction timeout) was reached.

HTTP 500: Internal server error

The GraphQL API cannot handle the request, due to an unexpected internal error.

HTTP 503: Service unavailable

The GraphQL API has encountered a situation where it is unable to provide a response (and cannot indicate why).

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!