A Field Guide To

Static Apps

Front-End Error Handling

When building a web application, it's often a little too easy to focus only on the golden path, building and testing only for situations when things go right. Unfortunately, things rarely go right all the time in the real world. Error handling is a vital part of any application's user experience, and if done well, can leave your users feeling informed and properly considered.

Most errors that an application encounters can be grouped into a few categories:

Almost every application will have instances of each of these error categories at some point. Handling each appropriately is key to keeping users who encounter errors from becoming angry users.

Front-End vs. Back-End Error Handling

In web application back-ends, expected errors are usually handled by displaying or responding with some kind of error message, while unexpected errors will short circuit the normal response process and display a generic error page. Applications that are very poorly configured might even spit out internal error details to the end user. For the most part, back-end applications are not always good at helping a user recover from an error, but they are pretty good at letting the user know something is wrong.

Front-end applications, for better or worse, have no built-in mechanism for halting everything and displaying an error message. When a JavaScript error occurs, usually one of three things happens:

  1. The application keeps running, but something the user expected to happen doesn't happen. The most common user response to this type of error is simply to try the action again (and again) hoping it will "work this time."
  2. The application stops running but displays no sign that it has stopped. The user will retry the action (or try to perform a different one) to no avail.
  3. If the error happened early enough, the entire page may be prevented from being properly set up and the user will just see a white screen.

These scenarios, from a user experience perspective, are terrible. They are likely to lead to user frustration, a feeling of helplessness, and eventual anger. Front-end applications are in many ways more flexible than back-end applications in how to handle and respond to errors, but you must handle the errors yourself. A browser's built-in facilities will be little help to the end user.

Getting it Right

There are many ways to implement error handling in a JavaScript application. You may define a global error handler that can display messages passed to it, or have each component or control handle its own errors.

One clean way to handle errors is to define a common schema for all of your application's errors and use the browser's built-in event system to "bubble up" errors that are then caught and handled appropriately. For instance, a form validation error might be caught on the form element (or relevant input) and displayed inline, while an unrecognized system error might bubble all the way up to the document and display a generic message.

User communication when an error occurs is vital. You need to tell the user what went wrong, but also what they should do now. In general those communications will be:

When handling client-side errors, you often have another choice to make: halt the application or allow it to continue running. If the error only applies to part of your system, you may want to allow the user to continue using the application. If the error is widespread or critical, however, you may want to display the error message in an undismissable modal window (or simply replace the page contents with the error message), preventing the user from fruitlessly attempting further action.

AJAX Errors and HTTP Status Codes

The simplest (and still a very effective) way to communicate general information about an error is to properly utilize HTTP status codes. These can tell you much about what has gone wrong with a request, and even without additional information give you hints about what to do next. These codes are split into 4XX codes (something is wrong with the request) and 5XX codes (something is wrong with the server). The most common statuses for web application errors are:

Know these codes, and know them well, and you'll be well on your way to handling any error that comes your way via an AJAX request.

Catching Errors

You can attach an error handler at a global level by using window.onerror. Once attached, your handler can override the default browser behavior allowing you to display information to the user as necessary.

window.onerror = function(message, url, lineNumber) {
  // detect if the error is something you know how to handle
  if (errorCanBeHandled) {
    // display an error message to the user
    displayErrorMessage(message);
    // return true to short-circuit default error behavior
    return true;
  } else {
    // run the default error handling of the browser
    return false;
  }
}

While this will work, it's often difficult (if not impossible) to entirely parse out the exact nature of a problem from a thrown exception. When handling AJAX errors, for example, a better practice is to use your favorite library's AJAX error function to detect the status code and react appropriately.

The most important takeaway for error handling is that you need to do it. Any step towards informing the user when something goes wrong is a good one. Even an alert() box is better than a silent failure. Remember, your application's user experience encompasses everything, not just the golden path.

Want to be featured here? Email us.