Error Handling in GraphQL

Overview

GraphQL is a powerful query language for APIs that provides a flexible and efficient approach to handling data. However, error handling in GraphQL differs from error handling in traditional REST APIs, particularly regarding the use of HTTP status codes. This document provides an overview of LeanIX GraphQL error handling and explains the nature of GraphQL not returning HTTP error codes.

Understanding Error Handling in GraphQL

Unlike REST APIs, which use HTTP status codes to indicate the success or failure of a request, GraphQL always responds with a 200 OK HTTP status code, even when an error occurs. This happens because GraphQL operations can result in partial success and partial failure at the same time. For example, when a GraphQL query is used to request multiple fields, some fields may return data successfully, while other fields may return an error.

In GraphQL, operational errors are treated as data, not as network errors. Therefore, the HTTP status code does not reflect the success or failure of the operation. Instead, the success or failure is communicated in the response body.

Error Handling in LeanIX GraphQL

When an error occurs in LeanIX GraphQL, the response includes an errors array in the JSON payload. Each error object in the array contains a message field that describes the error. It may also contain a locations field that provides additional information.

Here's an example of a GraphQL error response:

{
  "data": null,
  "errors": [
    {
      "message": "Validation error of type FieldUndefined: Field nonExistenField is undefined",
      "locations": [
        {
          "line": 6,
          "column": 9
        }
      ]
    }
  ]
}

Handling Errors in Your Application

When working with the LeanIX GraphQL API, ensure to design your application to handle errors in the response body, not based on the HTTP status code. Here are some steps you can follow:

1. Check for the errors field in the response: After making a GraphQL request, always check if the errors field is present in the response. If it's present, it means one or more errors occurred.

2. Parse the error message: Each error object within the errors array includes a message field. This field usually contains a description that can help you understand the nature of the error that occurred. Please note that the clarity and comprehensibility of these messages can vary, and they may not always provide a complete picture of the issue. We recommend using error messages as a starting point for troubleshooting, keeping in mind that they don't provide a definitive diagnosis of the problem.

3. View the error location: The locations field in the GraphQL error response is designed to provide specific details about where in the query or mutation the error occurred. It contains an array of objects, each with the line and column properties. The line property indicates the line number in the query or mutation where the error was encountered. Similarly, the column property specifies the character position within that line where the error was detected. In the provided error response, the locations field indicates that the error was found on line 6 in column 9 of the query or mutation.

Remember that the absence of the errors field in the response indicates that the operation was successful.