Errors as Data Explained

Union types in GraphQL are an excellent way to represent multiple types of data in a single field. This can be extremely useful when dealing with different types of responses, such as success and error cases. By leveraging union types, developers can create a flexible and expressive API that handles different scenarios elegantly and efficiently.

One of the core features of GraphQL is its built-in error handling mechanism, which uses an errors array in the response to represent any errors that occurred during the request. However, not all errors may want to be included in this array. If we are following the Errors as Data pattern, the errors array should be used for system errors—those that would typically result in an HTTP 500 error.

System errors can include situations like:

• Server crashes
• Unhandled exceptions
• Exhausted resources (for example, memory or CPU)

These errors are usually unexpected and can't be handled gracefully by the client. As a result, they should be logged and monitored on the server side, while the client should display a generic error message.

On the other hand, all other business logic errors, could be part of the known response types within the response union. This allows the client to handle these errors explicitly, providing better user experience and maintainable code.

In this example, we'll look at a checkout mutation that processes a user's cart and creates an order. The possible responses for this mutation could include a successful order creation, insufficient stock, or an invalid payment method. We'll use union types to represent these different response scenarios.

1
union CheckoutResponse =
2
    Order
3
  | InsufficientStockError
4
  | InvalidPaymentMethodError
5

6
type Mutation {
7
  checkout(paymentMethod: ID!): CheckoutResponse
8
}
9

10
type Order {
11
  id: ID!
12
  items: [OrderItem!]!
13
  totalPrice: Float!
14
  status: String!
15
}
16

17
type OrderItem {
18
  id: ID!
19
  product: Product!
20
  quantity: Int!
21
  price: Float!
22
}
23

24
type Product {
25
  id: ID!
26
  name: String!
27
  price: Float!
28
}
29

30
interface CheckoutError {
31
  message: String!
32
}
33

34
type InsufficientStockError implements CheckoutError {
35
  message: String!
36
  product: Product!
37
  availableStock: Int!
38
}
39

40
type InvalidPaymentMethodError implements CheckoutError {
41
  message: String!
42
  paymentMethod: ID!
43
}

In the schema above, the checkout mutation returns a CheckoutResponse union type that can be one of the following types: Order, InsufficientStockError, or InvalidPaymentMethodError. The client can handle each of these cases explicitly, ensuring a clear and expressive API design.

Now, let's look at a sample operation and the possible response handling:

1
mutation OrderCheckout($payment: ID!) {
2
  checkout(paymentMethod: $payment) {
3
    ... on Order {
4
      id
5
      items {
6
        product {
7
          name
8
        }
9
        quantity
10
        price
11
      }
12
      totalPrice
13
      status
14
    }
15
    ... on InsufficientStockError {
16
      message
17
      product {
18
        name
19
      }
20
      availableStock
21
    }
22
    ... on InvalidPaymentMethodError {
23
      message
24
      paymentMethod
25
    }
26
  }
27
}

In this mutation, the client requests different fields for each possible response type:

1. For a successful order creation (Order), the client retrieves the order details, including the items, total price, and status.
2. For an insufficient stock error (InsufficientStockError), the client retrieves the error message, the affected product, and the available stock information. This information can be used to display a user-friendly error message and suggest alternative actions, such as updating the cart.
3. For an invalid payment method error (InvalidPaymentMethodError), the client retrieves the error message and the problematic payment method ID. This can be used to inform the user about the issue and prompt them to update their payment information.

By using the union type CheckoutResponse, the API provides a clean and flexible way to handle the different response scenarios that can occur during the checkout process. This allows the client to handle each case explicitly, provides strong typing for operation responses and enhances the developer experience.