Writing better error messages for your apps

Apps are designed taking into consideration a happy path –the flawless journey– but hiccups happen. It could be a connection issue, the server might be down, or maybe the user entered the wrong password.

Errors are frustrating and they disrupt users’ experience. If something bad is happening, what should the app do? Should it blame the user? Should it give instructions on how to fix a line of code? Apps can, and should, help users overcome issues, but there is a right and a wrong way to do it.

UX Writing

Apps are crafted for the happy path, but sometimes "whoopsy daisy, something strangely wrong" happens. We've all been frustrated by error messages that are unhelpful and incomprehensible. Error messages should be tailored to inform users of what happened and guide them on overcoming issues while being friendly.

Error handling is crucial for the experience in any application. Even though an app is designed to be perfect, a part of the system can stop working without any previous notice and errors can occur.

Be consistent

Consistency is the not-so-secret key to effective UX writing. Error messages should maintain the same voice as the rest of the app to create a unified brand experience. The tone, however, can differ to deliver a more suitable message in a sad scenario.

The app should never be aggressive or blame the user, even if they made the mistake. Communicate clearly and honestly by writing to the human behind the screen, not the developing team. Communicate what users need to know and only that. Explain what they lost and what they didn’t lose (e.g. an error in a banking transfer should inform if the money moved accounts or not).

Never use codes or wording that users might not understand – e.g. tech vocabulary – this could intimidate users. If a problem that can be fixed appears, a lost connection issue, support how to enable it back. If it’s an incorrect input, tell what the field is expecting – give a sample of how the phone number should be entered. If a mistake happens the app should provide a supportive and pleasant experience, but don’t forget, an error is still an error.

Find the vulnerability

Before creating illustrations for errors, understand where and when the error messages will appear. Generally, an app usually has two types of errors: user-created errors, e.g. improper input. The second type is system-generated errors, like server downtime.

Mistakes in the user input are when incorrect information is submitted –invalid email or wrong password. To minimize errors, understand when user input is needed and validate on the spot to reduce mistakes, offering examples of how to type the information, "add phone number in this format". When user input is needed the input field should be logical and straightforward.

For quantities offer a numeric keyboard and provide intuitive choices –users are likely to buy 1, 2 or 3 coffees, instead of 0.5 or 100000 coffees. Validating the most appropriate input reduces mistakes improving the user experience.

Look and feel

With the writing concepts for error messages covered, the next step is choosing the best and native patterns to deliver the error. Alerts are, in iOS, the most common way to show an error message. Alerts should be only used for critical messages as they capture the user's full attention and interrupt the flow.

Some error types can't be present as an alert, such as those caused by the system. For these, a full-screen message, a modal view or a banner –similar to a notification– are the common way to deliver the message. If the error is related to a wrong input and the user can fix it right away, the standard way to communicate is by adding a note under the text field using the error color, to be easily perceived. Always opt for the least obstructing way of communicating the error.

Grouping errors for better communication

To communicate errors effectively, an easy technique is grouping similar issues to create an overview of messages. This enhances consistency among different types of error messages. One common method is categorizing messages by the level of emotion the error will evoke in the user. For example, errors like "User tries to finish the flow with missing information" can be grouped under "Frustrated," indicating the need for more detailed guidance to prevent such scenarios.

For the errors that users can't fix, provide ways to move forward or back. In the unfortunate event of an app crashing, offer alternative support options, such as an online help section or email support, as a last resource.

Don’t forget consistency in those channels; they should maintain the brand's quality and character. Delivering poor services will ruin the experience and risk losing users.

For further reading, BBC shares an insightful guide on writing error messages and Spectrum, Adobe's design system, features well-crafted documentation on how to write and display error messages.