What Is Error Format in GraphQL: Explanation and Example

In GraphQL, the error format is a standard way to return errors in the response using an errors array. Each error object typically contains a message describing the problem and optional fields like locations and path to help identify where the error happened.

How It Works

Imagine you ask a friend to help you with a task, but something goes wrong. Instead of just saying "no," your friend explains what went wrong and where. GraphQL does the same when something fails during a query or mutation.

When a GraphQL server encounters an error, it doesn't just stop or crash. Instead, it sends back a response with an errors array. Each item in this array is an object that tells you what the error was, where it happened in your query, and sometimes extra details to help fix it.

This format helps clients understand problems clearly and handle them gracefully, like showing a helpful message to users or retrying the request.

Example

This example shows a GraphQL response with an error when a query asks for a field that does not exist.

json

{
  "errors": [
    {
      "message": "Cannot query field \"age\" on type \"User\".",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["user", "age"]
    }
  ],
  "data": {
    "user": null
  }
}

When to Use

You use the GraphQL error format whenever your server needs to tell the client about problems during query execution. This includes validation errors, authorization failures, or runtime exceptions.

For example, if a user tries to access data they are not allowed to see, the server returns an error in this format. Or if the query asks for a field that does not exist, the error format helps the client understand what went wrong.

This consistent error format makes it easier to build user-friendly apps that can react properly to different error situations.

Key Points

• The errors array holds one or more error objects.
• Each error object has a message describing the issue.
• Optional fields like locations and path help pinpoint the error source.
• The data field may be null or partially filled depending on the error.
• This format helps clients handle errors clearly and consistently.

Key Takeaways

GraphQL errors are returned in a standard errors array in the response.

Each error includes a message and optional details like locations and path.

This format helps clients understand and handle errors clearly.

Use this error format for validation, authorization, and runtime errors.

The data field may be null or partially present when errors occur.