The Art of the Error Message

How to write clear, helpful copy for when things go wrong

Marina Posniak
Nov 9, 2017 · 5 min read
Error messages should point toward a solution, not act as a Band-Aid. Image: denkcreative/Getty

By Marina Posniak & Tamara Hilmes

he concept of embracing failure is big in the tech industry. “Fail fast, fail often” is almost an industry mantra. But there’s an everyday type of failure that doesn’t get much attention in the product development process: the humble error message.

The error message should help the user solve the problem and move on.

Error Messages Matter

We’ve all seen an “incorrect password” error once in a while (or, um, daily). While it can be frustrating when things don’t work as expected, we usually just brush it off as no big deal. But what’s the cumulative effect of these small moments?

Every error message is a tiny roadblock that gets in the way of what we are trying to do. Depending on the context, an unhelpful message can mean the difference between continuing or giving up. There’s even some research to suggest that error messages trigger a physical stress response by raising cortisol levels.

Just think of the difference between seeing something like this:

Image for post
Image for post
Needs work.

And seeing something more actionable, like this:

Image for post
Image for post

If you’re a writer, designer, or developer working on an app, you can help reduce your users’ frustration by being more thoughtful about the errors you display.

Ask yourself if you even need the error message. Before writing anything, consider if there’s a way to redesign the experience so there’s no error at all. Is there a way to just make it work? The best error message is no error message.

If you do need it, think carefully about the message. When things go wrong and the app fails, say something useful. The message should help the user solve the problem and move on.

Tips for Writing Helpful Error Messages

If you can’t fix the underlying issue and need to show an error message, here are some things to keep in mind.

Explain What Happened and Why

A lot of error messages are vague. Really vague. When possible, be clear about what’s going on. Give the right amount of detail, but don’t get too technical. Write in a way that anyone could easily understand. That means no jargon.

Imagine a user sees an ad about Spotify Premium and clicks on the link to start a free trial. Then they land on a page and see something like this:

Image for post
Image for post
Needs work.

It’s not clear why the user is ineligible, especially given that they just got an email saying, “Hey, get this thing.” What’s the deal?

In this case, it’s important to tell the user what happened (they’re ineligible) and why (they previously signed up for a free trial).

Image for post
Image for post

And yes, this message did get longer—but sometimes we need to add information to make it useful.

Suggest a Next Step

After you explain what happened, tell the user what they can do to resolve the issue. Include a button, a link, or another call to action. Write a clear headline that gets the point across quickly.

Imagine you want to look for some new podcasts. You fire up the app and see an error message:

Image for post
Image for post
Needs work.

This message tells you what went wrong and why, but it doesn’t suggest a next step. It’s better to include a clear headline (“app is out of date”) and a call to action (the download button).

Image for post
Image for post

Find the Right Tone

As UX writers, we want to convey the right information at the right time. But it’s not only about what we say, it’s also how we say it. When it comes to tone, we try to find the right balance—or, as we say in Sweden, lagom.

Tone refers to the character or attitude of the language. Within the same brand voice, your writing can take on a different tone depending on the situation. It can be more serious, neutral, or friendly—it all depends on who you’re writing for and what you’re writing about. You vary your tone constantly; just think about the way you talk to your friends, your parents, or your boss.

How do you choose the right tone? You can start by asking yourself:

  • How might the user feel in this situation? If it’s a stressful or serious issue, a silly tone would be inappropriate.
  • Would you actually say this? Reading the message out loud can help you pinpoint words or phrases you need to revise.
Image for post
Image for post

Bad request. Password supplied is invalid. → Words like “bad request” and “supplied” make it sound robotic.

That password doesn’t match. Try again? → This one’s pretty clear and approachable. Nice.

Problemo! The password you provided doesn’t match. Wanna try that again? → Would you actually say this? It’s a bit too silly.

These three messages communicate the same thing, but the tone is different. When you’re writing an error message, choose the tone that best fits the audience and context.

he difference between a good and bad user experience often lies in the details. Writing clear error messages can reduce frustration and help people continue using your app or service. It’s worth it to give these users some love. Next time you’re writing an error message, keep these tips in mind:

  • Say what happened and why.
  • Suggest a next step.
  • Find the right tone.

And don’t forget to read the message out loud and take out any pesky jargon.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store