A good error message is two error messages
An error message has two audiences:
- the end user seeing the error;
- and the developer trying to figure out why we got this error.
As such, a good error message should have two parts, one for each consumer of the error message.
The end user
The end user should be shown an error message telling them that something has in fact gone wrong and maybe not everything will look or work as expected.
Ideally, the error message would also be actionable and indicate what the user can do. However, this is very rarely possible. In most scenarios we build for the happy path. In some cases we can gracefully handle or show one or two possible error paths. If so, good. In most cases though, the error indicates that something we did not think was going to happen, did in fact happen.
So a good error message for the end user should be kept generic and neutral. Don’t insult your end user by trying to be
funny, no one appreciates reading a tongue-in-cheek message after they wanted to do something. Keep it short, sweet and
generic. An error occurred while uploading the invoices is a good error message.
The developer
For the developer you want to give as much context as possible. Why? Well because the error report you’re going to get sent to you is going to be an image of the error. So when you get assigned the issue chances are that you won’t have a link to see how to trigger the error, or maybe you can’t reproduce it any more.
So, add all the context that you can here. Don’t leak secret data of course. But everything you sent in your request and returned in your response is already available to the user, so show that at the very least. Ideally, you want to have enough information here to figure out just from the image what we attempted to do and what exact error we received. Without a link or way of reproducing the error, you should still have a good starting point.
Combining the two
Put the end user’s error message at the top in larger text. Then, in monospace and slightly smaller text put the developer’s error message. The monospace fonts tells the end user that this is in fact something technical and not intended for them.
Here’s an example of this in action. Here, we also have the possibility of having a very large error message for the developer by using an accordion to hide the developer’s error message.
Beware that this method may backfire! You might get a picture of the error message without the accordion expanded and then you just have the end user’s error message. Very sad! However, it might still be preferable compared to having the an error message the size of the end user’s screen, that does not look good…