Centralized error handling with GraphQL

[lpglinard]

This discussion item is related to #55 .

[Cintyabio]

Error Handling in GraphQL

GraphQL is a query language for APIs (Application Programming Interfaces) and a runtime for executing those queries with existing data. It’s a more flexible and efficient alternative to REST APIs, allowing clients to request exactly the data they need, avoiding overfetching or underfetching of information, which is common in REST APIs.

What happens when we make a query and something goes wrong?
You get an error. And you can find it in the errors array. Canonically, this is where errors can be found in a GraphQL response. However, in more complex queries, it’s harder to know where the error came from—especially if there’s, for example, a list of items.

Error Categories

When we start thinking about “errors,” we can separate them into categories. Errors like Internal Server Error and Bad Gateway indicate that something truly went wrong with the request. So, these are definitely errors.
But in cases like Deleted User, Unavailable in Country, and Suspended User, nothing actually went wrong. These aren’t the expected results most of the time, but they’re certainly not errors. They’re results, because the query was executed and returned that information.

How to Handle These Presented Errors

We can use a Union (perfect for representing one of several states!) to create a UserResult that encompasses all these possible outcomes.

For example, if we have a Deleted User, we could include a Message, or if our user is Suspended, we could include a Policy Violation Link. Instead of just receiving an error, we’d get the cause of the result.

With this approach, we can have customizable results for each entity. We know exactly where the error in the query comes from because it’s encoded in the schema, and the client decides which errors matter and which can be ignored.

It’s possible to model results for different entities in the same query. This allows one result to fail while the other can still be presented if there’s no error.

GraphQL intentionally does not prescribe how to model your schema, and the same goes for errors and results. It’s up to you to decide what best describes your data, giving you the freedom to model it.

Examples:

When we make a query, depending on the type of result, it’s possible to choose which data to show and how to present it.

{
  userResult(username: "@ash") {
    __typename
    ... on User {
      id
      name
    }
    ... on IsBlocked {
      message
      blockedByUser {
        username
      }
    }
    ... on Suspended {
      reason
    }
}

We get this as a result:

{
  "data": {
    "userResult": {
      "__typename": "User",
      "id": "268314bb7e7e",
      "name": "Ash Ketchum"
    }
  }
}

Let’s suppose this user is actually not available. If we run the same query again, we get this result:

{
  "data": {
    "userResult": {
      "__typename": "IsBlocked",
      "message": "User blocked: @ash",
        "blockedByUser": {
          "username": "@brock"
        }
     }
  }
}

Instead of receiving an error, we get IsBlocked and a result with all the fields we requested in an IsBlocked response.

Share your ideas in the comments on new ways to model queries in GraphQL!