On writing better error messages
You're browsing your favorite website, clicking around, when suddenly, you're rudely interrupted by a white screen, proclaiming:
Error 503 Service Unavailable
(I don't mean to pick on Varnish cache here, It's just a screenshot I had handy)
As a developer, my eyes scan error messages like these for numbers - in this case, the "503" - indicating that the error isn't my fault, and I can move on with my life.
Unfortunately the majority of internet users aren't trained in the art of reading HTTP status codes, so this error message isn't particularly useful to them.
How to write better error messages
The majority of internet users aren't developers, so outputting the HTTP error code and its name (503 Service Unavailable) isn't good enough.
The Nielsen Norman Group back in 1998 (!) provided us with some basic guiding principles for writing better error messages:
- Write in plain English (or whichever language you're supporting)
- Tell the user exactly what went wrong
- Tell the user how the problem can be fixed
More concretely, we can write better error messages by answering the following four questions:
- Who caused the error?
- What happened, and why?
- When will it be fixed?
- How can the user respond to the error?
If your error message covers those four points, then you can think about adding humour and some brand identity.
Note that humour and brand identity should never interfere with telling the user how to resolve the issue as briefly as possible:
Who caused the error?
The last thing you want to do is make your users feel dumb, or as though they're at fault for an issue with the service. Communicating who caused the error helps clear up any confusion.
Explicitly focus on "we" when the error is caused by an issue on your end (typically HTTP status codes in the 5xx range).
An error message such as
Our service is down for maintenance
is infinitely better than:
Uh-oh! Something went wrong!
For errors caused by the user (typically HTTP status codes in the 4xx range), be explicit about that too. For example, a 403 Forbidden error (where you know the user isn't authorized to view content) could be communicated as:
Access Denied. You do not have permission to view this page.
What happened, and why?
While users may not be technical, they still need an explanation of why they're seeing your error screen.
Take the classic 404 error message: "404 Not Found". You can make it significantly better for non-technical users with a single word:
Page not found.
adding a "why", makes it even better, giving them a way to fix the issue:
Page not found. You might have mistyped the URL.
When will it be fixed?
It's relatively difficult to keep an error message updated with with details of your outage, and when you expect the service to become available again.
A better approach would be to link to either your status page, or Twitter account, or both, as in GitHub's case:
How can the user respond to the error?
In the case of a 404, you might want to list some steps the user can take to fix the issue, such as:
- Going back to the home page
- Using your search bar to find the page if it's been moved
- Contacting support
Whereas in the case of a 5xx server error, you want to communicate to the user that there isn't much they can do, and that it's not their fault.
My favorite example of a company doing this well is Airbnb:
They tell users:
- there's definitely an issue, and they're working on it,
- to check out their Twitter account for updates,
- a way to get support for urgent issues,
- and they set the expectation that they may be slow to respond while the site is experiencing downtime
Summary
We as developers need to improve our error messages. Try to be helpful, and explain:
- Who caused the error?
- What happened, and why?
- When will it be fixed?
- How can the user respond to the error?
Depending on the type of service you run, you'll likely still need request IDs and other diagnostics in your error message to help your support staff debug the issue.
A human-readable error message doesn't have to come at the expense of removing all technical information.