Errors

Despite our best efforts, some errors are inevitable. As such, clear error messages that tell people what happened and what they can do about it are essential. That’s why we should embrace errors and the messages that explain them as make-or-break moments to build trust and salvage experiences. 

Work with your product designer to understand if there are visual or interaction design patterns you can use to prevent errors, like warning messages or helper text.

How to think about writing error messages

Designing error messages shouldn’t be a last-minute project. At the beginning of the design process, think about possible errors that could occur in the experience. Always account for common problems like data sync failures, lack of internet connection, insufficient permissions, back-end failures, and more.

Are there alternatives?

Error messages won’t fix a broken experience. Before drafting an error message, consider how you could improve other elements of the experience to prevent the error in the first place. 

Sometimes, page-level error messages aren’t necessary. Use field-level errors so people know which info to change before they can move forward.

Design for the least amount of errors. Give people the flexibility to make an informed decision about what to do next before getting blocked by an error.

Don’t provide an error message after-the-fact when we know they’ll be blocked.

Investigate

Ask engineers, product designers, and product managers on your team for more context, like requirements, edge cases, solutions, and possible causes. If there are multiple causes that could trigger an error, make sure you have a good grasp of each. This will make it easier to design relevant and helpful messaging later.

Gather

If you can reproduce the error in product or staging, find screenshots or video references for what’s going on in the context of the full flow.

Write for the error, not the container

Decide on the message before choosing a component for it.

Collect

Over time, build out your own collection of error messages for your projects. A shareable doc that’s easy to update can be a valuable resource for you and your partners.

Principles

Be clear

Use simple language to explain what happened (the error) and what people can do about it (the resolution).

Only communicate the cause of the error if people need to know it, and you can explain it in plain language at a 5th- to 8th-grade reading level. For more info, see our readability guidelines

Avoid error codes

Don’t include error codes in your messages. They’re clunky, technical jargon that often fail to provide meaningful information. Instead of helping people understand and resolve issues, error codes can cause confusion and frustration. And most of the time, the solution for an error code is to try again later. 

Prioritizing clear, user-friendly error messages over technical codes aligns with our goal of delivering a seamless and intuitive experience to the people who use our products. You can always work with your engineer to make sure error codes are logged on the back-end for later debugging. But no one else has to see them. 

Keep it brief

Multiple lines of text are hard to scan. This is even harder when you’re frustrated or stressed, as people often are when encountering errors. Make things easier on people by writing a brief message. 

But remember: Clarity trumps brevity. It doesn’t matter how short your error message is if people don’t understand what’s happening or what to do next.

Be helpful

When possible, error messages should help people resolve errors quickly. Try to give them a one-click solution (like a button or link) so they can resolve the error themselves. If that’s not possible, link to a support article. Feeling empowered to resolve most errors themselves gives people more confidence when using our products and spares them from calling customer support. See our guidance on Actions

When people can’t resolve the error themselves, work with your team to find the best solution to get them the help they need. This could include providing a phone number or link to chat with customer support. But, before doing so, check with your customer support partners to make sure they’ll be able to help. 

Avoid humor or cleverness in error messages. Even for low-stakes errors, people won’t feel like laughing in already-tense situations. Besides, what might be funny to some can seem condescending or inappropriate to others.  

Lastly, some people might interpret humor in the context of an error message as distracting or making light of their problem. This isn’t helpful and only adds to people’s frustration.

Be specific

If you have precise info on when someone should check back after facing an error, be sure to include it. Being specific reassures people that the situation is controlled and manageable. If you can’t provide exact info, try to be transparent about it. 

It’s important to be specific and clear, but there will be times when we don’t know what’s happening. In these cases, it’s OK to keep it generic with something like “Something isn’t working. We’re fixing some things on our end. Try again later.” But it’s still worth checking with engineers so you have a good grasp on potential error causes.    

Though it’s not ideal, sometimes we need to say “try again” or “try again later” as the only realistic solution to an issue. Giving people the option to “try again” is always better than leaving them at a dead end. However, limit the “try agains” when there’s a more specific action you could provide.

Voice and tone

Use passive voice sparingly

Use active voice most of the time. However, passive voice can be a powerful tool. For example, you can use passive voice when the person or thing that performs the action of the sentence isn’t important. Passive voice can also help with brevity, softening the blow, and avoiding blame when the error was caused by the user. Learn more about active and passive voice

Avoid blame and judgment

We always want to avoid blaming or judging, even if the user caused the error. Instead of emphasizing their mistake, focus on the problem and how to fix it. When the error is our fault, we can communicate that as long as it’s relevant. However, use “sorry” sparingly. Learn more about keeping language positive  

Match tone to severity

Error messages can trigger a lot of negative feelings. We can make the situation even worse if we use the wrong tone. Use the following framework to match your tone to the severity of the error:  

Minor errors

People can usually fix this type of error themselves with the least amount of time and inconvenience. Calls for a more casual and conversational tone. 

Examples:

• Someone enters the wrong password 
• No internet connection 
• The credit card on file is expired  

Moderate errors

People can fix this type of error themselves, but it may require more time and effort. These errors can be more complex to fix either because there are more steps involved or because the user needs to ask someone else to help (as with a permissions error). Calls for a neutral tone that gets straight to the point and offers a one-click solution.

Examples:

• Someone doesn’t have the required permissions to access something 
• User needs to call their credit card company to authorize a purchase 
• Someone needs to wait for their data to sync before doing a task

Severe errors

People can’t fix this type of error themselves, and it may result in significant inconvenience in terms of time, data loss, financial difficulties, etc. Convey the message in a neutral tone to avoid escalating an already-tense situation.

Be careful what you say. For example, never communicate that we suspect fraud in the event of payment failure because a) the system could have a bug and b) we don’t want to give out sensitive info that could end up in the wrong hands.  

Examples:

• Failure of an application resulting in data loss  
• Payment failure due to suspected fraud 

If it’s a serious issue resulting in data loss or other consequences that could negatively impact someone, we can link to detailed instructions and suggest people call customer support. 

Words to handle with care

• Error. This word is overly negative and states the obvious. People know when they’ve encountered an error. 
• Please
• Sorry
• Hmm, yikes, and similar words. This type of word might imply we don’t know what’s happening and may add to people’s frustration.
• Whoops, oops, and similar words. These words can give the impression that we’re making light of an error, which can also add to people’s frustration.
• Wrong. This word is overly negative and could imply blame or judgment.
• Overly technical, negative, and non-inclusive words, such as invalid, prohibited, restricted, fail, failure, declined, denied, forbidden, fraud, and suspended. 

What to include

Error messages usually consist of 2, or sometimes 3, things:  

1. Headline
2. More info (optional) 
3. Call to action

Headline

Tell people what happened or what they can do to fix the problem. 

If it’s our issue, be transparent about it so people know they didn’t do anything wrong. If it’s a user error, avoid blame—instead, focus on the error’s effect on the user and how to fix it. 

Try to keep headlines to one line. 

More info (optional)

If we have more info that people need to know, we can include body content. 

We want to keep error messages brief, so it’s great if we don’t have to include more content.

Calls to action

Tell people what to do to solve the problem, like trying again or contacting customer support. 

If the solution to the problem is easy to understand and do and is guaranteed to work, you can put the call to action in the headline. This strategy will help keep the message brief and to the point. 

Use your best judgment when deciding whether to have one primary CTA with the most important action or a primary and a secondary CTA.

Follow our grammar and formatting guidelines when writing error messages.

Error messages from third parties

Occasionally, we need to show people error messages from third parties, such as financial institutions. To make this experience less jarring, craft a brief error message and then follow that with the content from the third party, preferably highlighted in a callout box.