How do you write user-friendly error messages for your web app? (2024)

I try to think about it this way: how would I explain this to my mom (if non-technical users are part of the audience)? And all error messages should clearly state how they can fix the problem.

Because not all of our users are first-language speakers, we have to be careful with words such as "please" (that can indicate that the action is optional, rather than a polite phrase) or "may" (that can indicate seeking permission, rather than possibility). Lead with action verbs and stick with the formula of a) What went wrong? b) What can you do (and how you can do it)? and c) What can you do if the action doesn't work? For example, "Enter a valid email by using the name@domain.com format. If the system doesn't accept the email, contact Customer Care at 1-800-HELP-MEE."

It's essential to provide guidance for immediate action. For example, a message such as "Contact Customer Care." results in the user having to "hunt" for contact information. On the other hand, a message such as "Contact Customer Care by using the care.example.com portal or by emailing care@example.com." provides information that the user doesn't need to search for. This is particularly important for mission-critical system where the user can't spare any time to search of browse for essential information.

It's a good idea to create a series of example error messages (or possibly a template) and include these examples in your in-house style guide. This allows everyone at your company, from Engineering to Customer Success, to speak with one voice. In turn, this approach creates a consistent and familiar experience for your users.

One of the best way to test error messages is simulating the situations in which they usually arise. For this reason, it is also a great idea to reach out to colleagues in Sales and Customer Success organizations and interview them about specific experiences in which the error messages arose, gauge the usability of the error message itself and its usefulness in the context of a scenario that involves a real system or customer.

In addition to accessibility, it is also important to make sure that your error messages are consistent across the product, for example, in the web UI, in the CLI, and in the SDK. A good single-sourcing strategy can ensure that your team reuses strings rather than writing them over and over for the same scenario. When you display error messages visually, match your product's design language and the severity and error type. For instance, you could have "Caution" error messages (that appear when damage to equipment or users can take place) appear in red, "Important" error messages (for data loss or corruption) appear in yellow, "Note" messages (information about unexpected system behavior) appear in blue, and "Tip" messages appear in green.

In addition to successful error message examples, it is a good thought-experiment to seek out confusing error messages, and try to imagine the ways in which you might rewrite them to serve the user better. By exposing yourself to as many kinds of error messaging and notification types "in the wild," you can get a good idea of what kind of system behavior expectations users commonly have and how far your can push your interface design.

A story about how NOT to write error messages: Many years ago, I worked for a company where I had inherited the Error Message Guide. The guide was a PDF file, hundreds of pages long. Most of the messages in this guide included an abstruse error code, a fairly user-unfriendly message, and often no resolution. Curating this monstrous deliverable taught me the importance of serving error messages in the immediate context where they occur (within the product itself). The sheer torture—of having to find the PDF file, search the file for a particular string, and then decipher it—is something I wouldn't wish on my worst enemy, and I have been avoiding these kinds of error messages since that time.

At a previous role, for insurance software, there was a list of all the error messages. No-one had bothered to 'clean up' or at least attempt to review the text within. So I asked for a dump of every single message and after a few days I had collated all of the necessary changes. Some of them were quite embarrassing and fixes were needed a.s.a.p. There were the simpler ones also, like removing an unnecessary 't' from Alzheimer's (and putting in the apostrophe). Always get a fresh pair of eyes to review *all* of the error messages. No matter how perfect your team think they are.