How to Communicate Errors Well (and Write Good Error Messages)

How to Communicate Errors Well (and Write Good Error Messages)

It's late evening and you're sitting in front of your computer trying to order pizza online. You're starving.

A large salami one.


Pay with credit card.

Error while processing order (E3428)

What the h...?

Will I get the pizza? Did they get my order? Was my credit card charged? Can I try again? Should I order by phone? Is the place closed?

You know you'll spend the next 30 minutes on phone trying to figure out what happened and what to do next. What a crazy evening.

But the sad truth is that errors happen.

The more complex the software is, the more often we have to say "sorry" to our users.
This means that it's not enough to think only about the "happy path" when building software products. In order for our users to really enjoy a product, it also needs to communicate bad news well.

Take a look at Spotify, for example. Here's an email you'll get when your subscription payment bounces.

Spotify email about payment declined

It clearly states that there's a problem (your payment failed), explains the consequences (things will continue to work for now) and tells you how to resolve it (click this button below and update your credit card details).

This kind of message makes the user more comfortable with the problem and provides a bunch of handy information.

In order to make error messages helpful, we need to make sure they clearly answer the questions our users will have when seeing them.

What Has Just Happened?!

First, tell the user why they're seeing the error. Even though your knowledge on this is probably also limited, give them the best insight you can.

Make sure that you communicate this in a way that can be understood by them. Neither internal jargon or debug messages will do any good here, they will rather bring even more frustration.
Remember that your user is not a developer, so they don't have deep knowledge into how the application works. And even if they do, they won't have much fun debugging your app. They just want to use it to achieve their goals.

Dropbox error message when trying to access deleted file
Dropbox showing the exact reason why a file cannot be accessed

Let them know if it's them who messed up or if that's a problem on your side.

If they're trying to order from a restaurant that's too far away, tell them that.

If you know that the payment processing service is down, tell them that as well.

Knowing what happened makes the experience less scary, for some it even gives a sense of control. People generally understand that credit card systems stop working once in a while and won't blame you for that. On the other hand, "An error has occurred" message makes your app look like it simply doesn't work.

What Did I Do Wrong?

If the error was caused by the user, you'll help them a lot if you tell them what their mistake was and how to fix it.
And while doing that, be as precise as possible.

Trello telling the user exactly why they think this email is invalid

Think of a situation when the user tries to make a payment, but the transaction amount exceeds their credit card limit.
This is definitely a problem on the user's side. We could communicate it as "There's a problem with your credit card".

But let's give it some more thought. Looking at it from the user's perspective, is that message really helpful? Exceeding the limit is only one of things that could have happened. Just take a look at stripe's docs regarding reasons why payments can be rejected.

By showing them the exact reason, you give them a chance to quickly fix the issue on their side and continue using your product.

What Are the Consequences

An error in your app usually means that the user wasn't able to complete an action. Some actions are extremely sensitive and it may be sensible to reassure the user in advance.

Take the checkout process as an example - it involves money and getting stuff delivered at your door. And as we all know, people freak out about that a lot.

If there's a problem during the checkout, they'll want to know what happened to their money. Was their credit card charged or is the money still there? Did you receive their order or should they try ordering again?

A lot of questions like these pop up in your users' minds. A good error message describing what will happen (and what won't) will save them a lot of worry.

What Should I Do Now?

Finally, since errors prevent users from achieving their goals, you may want to give them a hint on what they should do next.

Should they place a totally new order once their credit card issues are resolved? Or should they just retry paying for the existing one?

If there's an issue with your credit card service, maybe there's an alternative way of paying? Maybe they could pay upon delivery.

Any sort of guiding them through what they should do now will be extremely helpful. Also, if there's any way to automatically resolve the problem, you should definitely provide a link to it.

Design with Errors in Mind

We cannot avoid errors in our apps. They'll keep popping up more and more often as the business grows.

The one thing we can do for our users is to treat failures as an integral part of the app. When designing with errors in mind, we can be sure that they won't spoil the overall experience of our app.

So, with each feature look for things that can go wrong. Then put yourself in your user's shoes and think how to reduce the anxiety caused by error messages. Make them descriptive and helpful by answering the most common questions people may have.

Ultimately, you don't want your customers to walk away from you when something unexpected happens. You want to give them a hand!

Check out my latest post: Save Money by Not Building Features

Did you like this?

We write about building software products, no fluff included.
Leave your email and we'll let you know when we publish a new post.