Error & success messages
Guidelines for writing clear, helpful error and success messages that guide users effectively.
Error messages
Things don’t always run smoothly. Our systems can fail. It’s important to craft clear, logical, and accessible error messages that help folks get things done.
Understand the error
Before writing anything, make sure you know the answers to these questions:
- What happened?
- How did it happen?
- How can it be fixed?
- Is it a user or system error, or both?
How can we expect a user to know what’s going on and how to fix something if we don’t?
Set a basic structure
A good error message structure explains what happened and what can be done about it. A good error message has the following structure:
Here’s an example of an inline form error message:
If we can’t place the specific error, we’re deliberately vague. The best we can do is tell the user how they might fix it.
Keep it short and simple
We want to help folks fix errors quickly, so error messages should be concise. Strip out unnecessary words. Keep detail only when it’s relevant.
Don't
- "Can't create 'Engineering' because a team with that name already exists. Specify a different name."
- "Your notification failed and needs to be re-authorized."
Do
- "'Engineering' already exists. Try another team name."
- "Notification failed, please re-authorize it."
Consider etiquette
System error
Apologize when it’s the system’s fault and let the user know it’s not their fault. Use an active voice to accept responsibility. For example:
Don't
- "Your changes couldn't be saved."
Do
- "We couldn't save your changes."
User error
Sometimes it’s the user’s fault, but there are ways to tell them without sounding like we’re pointing the finger. For example, we can focus on the desired action rather than telling the user they’ve messed up:
Don't
- "You've missed your name."
- "You can't leave this blank."
Do
- "Please enter your name."
- "Please enter a team name."
A passive voice can work for more serious user errors, such as “This card was declined”.
Use the right tone
Tone is how you say something. A message’s tone should depend on how serious the error is. Warmth is great for less serious errors, but avoid anything too lighthearted for serious errors.
Avoid mechanical language and jargon, opting for plain language at all times. The aim is to make a user feel like you’re there, helping them solve the error.
Don't
- "The password entered does not match our records. Please re-enter your password."
Do
- "That password's not right. Try again."
At the same time, error messages are not the place to be clever or make jokes. This will only muddy your message and add to your user’s frustration.
Don't
- "Whoops! Looks like your card was declined. Better ask Mom for another one."
Do
- "This card was declined. Try another payment method."
What happens next
Some errors might need a button or link to fix or dismiss the message.
Always say what happens next. Buttons and links should make sense when read in isolation. Avoid just using things like “OK”. “OK” can be used to dismiss a message or take an action. Be clear to the user what they’re saying “OK” to.
Don't
Do
Design, placement, and timing
Error messages should take the whole user experience into consideration. It should be clear what triggers an error message and what it’s related to.
- Inline validation styles are best for displaying errors in UI with form fields.
- Inline notifications are best for displaying errors in UI without form fields. They should be located within close proximity of items that affect a feature.
- Modals are best when you want to ensure you capture someone’s focus.
Toast notifications are best for confirming that an action someone performed is taking place or successfully completed. Since they appear away from the layout and disappear after a few seconds, toast notifications aren’t recommended for error messages.
Success messages
It’s important that we keep users informed when actions are successfully completed. Success states throughout the user flow let users know that they’re either getting closer to achieving the goal, or have completed it.
Understand the situation
Before writing anything, make sure you know the answers to these questions:
- How close is the user to achieving the intended goal?
- What does the user need to do next?
- Is this message likely to appear frequently or is it unique?
Be specific
A good success message provides clear information that the performed action was completed. It’s fine to let users know that what they did was successful, but even better to be specific about the action they took.
Don't
- "Successfully saved."
- "Upgrade complete."
Do
- "Your account details have been saved."
- "You've upgraded to the Business tier of Teams."
Use the right tone
Tone is how you say something. Excitement makes sense for successfully finishing a large task, but avoid overdoing it for a regular system success. Limit exclamation marks to one per page.
Don't
- "Thanks for updating your email."
- "Account created."
Do
- "Your email has been updated."
- "Thanks for signing up. Your account has been created."
What happens next
Is the successful action part of a larger goal? Are there other recommended actions that need to be performed? Success messages can be a good way to guide the user to the next action for a more seamless interaction.
Don't
Do
Design, placement, and timing
- Inline validation styles are best for displaying success in UI with form fields.
- Toasts are best for common success messages. Since they appear away from the layout and disappear after a few seconds, these are great for simple actions that were successfully completed.
- Modals are best when you want to ensure you capture someone’s focus for a decision.