GraphQL error format

Introduction

GraphQL error format shows problems clearly when something goes wrong in a query. It helps developers fix issues fast.

When a query asks for data that does not exist.

When a user sends wrong or incomplete information.

When the server has trouble processing the request.

When a required field is missing in the query.

When permissions prevent access to requested data.

Syntax

GraphQL

{
  "errors": [
    {
      "message": "Error message here",
      "locations": [
        { "line": 2, "column": 3 }
      ],
      "path": ["fieldName"],
      "extensions": {
        "code": "ERROR_CODE",
        "details": "Additional info"
      }
    }
  ]
}

The errors field is an array because there can be many errors.

message explains what went wrong in simple words.

Examples

This error shows that the query asked for a field 'age' that does not exist on 'User'.

GraphQL

{
  "errors": [
    {
      "message": "Cannot query field 'age' on type 'User'.",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["user", "age"],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

This error tells the user that the 'email' field is missing in the input.

GraphQL

{
  "errors": [
    {
      "message": "Field 'email' is required.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["createUser"],
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Sample Program

This query asks for 'name' and 'age' of a user. The server replies with an error because 'age' is not a valid field.

GraphQL

query {
  user(id: "123") {
    name
    age
  }
}

/*
Server response:
{
  "errors": [
    {
      "message": "Cannot query field 'age' on type 'User'.",
      "locations": [{ "line": 4, "column": 5 }],
      "path": ["user", "age"],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}
*/

Important Notes

The locations help find the exact spot in the query where the error happened.

The path shows which part of the query caused the error.

Extensions provide extra info like error codes to help handle errors programmatically.

Summary

GraphQL errors are returned in a clear, structured format.

Errors include message, location, path, and optional extensions.

This format helps developers quickly find and fix problems in queries.