Error Handling

Overview

Current (12/10/2020)

There are a number of different ways that Caseflow is handling errors depending on what application and even which endpoints are being accessed. Often there are differences in the way that errors are formatted on the backend in the controllers and how the frontend then renders those messages to the user. It can be very challenging to understand which formats are used in which places which has lead to the effort to unify error formatting throughout Caseflow.

This document attempts to document the way that errors are currently being formatted in the different parts of the application so that we can begin refactoring the formats into a single pattern. Errors are grouped based on the application that is using that specific format and differentiated between frontend/backend formatting.

Hearings

Frontend

The Hearings App uses 3 different methods on the frontend to handle errors:

1. Using the Alert component for page-wide alerts: Example
2. Using the StatusMessage component for static alerts generated by the frontend only: Example
3. Inline with the form inputs: Example

Alert

The Alert component uses the following format to display errors as well as other types of messages:

{
  message: String,
  title: String,
  type: String
}

NOTE: This component is also used frequently within the Hearings App in conjunction with the UserAlerts component which takes an array of alerts and renders a list of Alert components.

StatusMessage

The StatusMessage component uses the following format to display errors as well as other types of messages:

{
  messageText: String,
  title: String,
  type: String
}

The main difference between the ways these 2 components are used is that the StatusMessage component is always used to render static text provided by the frontend, whereas the Alert component is sometimes used for static text and other times used for errors returned from the backend.

Inline Errors

For the first 2 methods, there are components to handle displaying the error messages. The inline error messages, however, use a different method for each input and in some cases the error messaging is separate from the input component see the example 3 above.

Backend

There are several different error formats that the backend will respond with to any frontend requests:

• Example: errors: [message, code]
• Example: errors: [{ status, title, detail}]
• Example: error
• Example: error, detail, type
• Example: errors: [title, detail]
• Example: errors: [title, details]
• Example: errors: [title, detail, status]

There are a few cases where the endpoint is not responding with an error, but rather returning a valid response with the errors attached to the body see this example. This causes the handling of these errors to be treated differently (as can be seen here). In order to correctly send error messages to the frontend that will trigger the catch block and not just be attached to the body is as follows:

# Status must be at the same level as json
render(
  json: {
    errors: [
      title: String,
      details: String
    ]
  },
  status: Symbol
)

Due to these inconsistencies the frontend code is handling the errors in different ways depending on which endpoint is being accessed. Additionally, because there is not uniformity in the formatting, in many cases the frontend is ignoring the returned error entirely and returning a custom error (see this example)

Queue

Intake

Reader

Notes

Technical Research

• Hearings App