A well-formed error message has the following elements:

• A unique identifier
• A short description of the problem
• A suggested remediation

If you want to be really generous in your error messages, you can also give people a way to report the error from within the error message, or contact support.

So how does that look in real life? Here’s an example from T-Mobile:

Msg 2114 - Message sent using invalid number of digits. Please resend using a 10-digit number or valid short code.

You can see that there is a number, so we can look up more information about this error if we want. After all, if there’s not a specific number, it’s really hard to find it on StackOverflow. Next there is a description of why the system does not like what happened. Finally, there is a suggestion for how you can fix the problem.

Not all errors are as straightforward as sending the wrong number of digits in a text, but we can do our best.

Remember that when a user is seeing an error message, something has just gone wrong while they were trying to get on with their day, and they are angry or stressed out. The most compassionate and helpful thing we can do is write an error message that is more useful than a notorious “Unexpected Server Error” message that is the catch-all for errors no one bothered to document.

Happy writing!

HW