Error messages
Error messages notify the user that something is not working as expected. Write clear error messages that tell users where, why, and what happened, and what they can do about it.
Tips
- Before drafting an error message, consider how you could improve other elements of the experience to prevent the error in the first place.
- Use helper text or information banners to prevent users from getting an error.
- Place error messages in proximity to where the error is triggered, both in the UI layout and moment in the flow.
Principles
Make it actionable
- Errors should explain what happened in simple words and what the user needs to do next.
Be clear
- Use simple language to explain what happened and what users can do about it.
- Only communicate technical details of the error if users need to know.
Be brief
- When an error is presented as a toast notification, it only stays on the screen for a short amount of time, and can be hard to read. Avoid using multiple lines of text.
- If the message is too long and needs more explanation, add a link that guides users to a help article.
Be helpful
- If possible, provide a one-click fix. If that's not possible, offer troubleshooting instructions, link to a help article, or redirect them to the help center. Before doing so, check with customer support partners to ensure they’ll be able to help.
Be specific
- Reassure users 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 clear and specific, but there will be times when we do not know what the exact problem is. In these cases, it’s ok to keep the message generic, e.g. “Something isn’t working. Try again later.”
- Use precise numbers and dates.
Be understanding
- Use understanding language to explain an error or a limitation.
General errors
In situations where we can’t offer a clear solution or the exact cause is unknown, “Something went wrong” is sometimes all that we can tell the user. In this case, use “Something went wrong” as a title. If there is body text or space to offer more information, use it to help the user as much as possible.
Error message types
Alert
Content
Title
- Tell users what happened or what they can do to fix the problem.
- Try to keep headlines to one line.
Body
- Keep error messages brief. It’s not necessary to include body text if the error can be addressed with a title.
- In some cases, users need to know more to solve the problem. In these cases, include body content.
- If the message is too long and needs more explanation, add a link to a help article.
Link
- Use a link if you need to direct customers to a page or a specific action.
- If the solution is too complex, you can link to a help article.
- We do not link to external documentation in our error messages (e.g. Stripe or Adyen documentation). Always look for a Mews guide to link to.
Dialog
Content
Title
- Tell users what they can do to fix the problem.
- Try to keep titles to one line.
- Avoid using variables in title text.
Body
- Explain what happened. In some cases, users need to know more to solve the problem. In these cases, include body content.
Button
- Button text should indicate the next action that the user will take.
- Keep button text short, with a maximum of 3 words.
Helper message
Content
- Keep it as brief as possible.
- Since the message is directly below the text field, the copy only needs to explain what to do next. Optionally, the message can explain why the error happened.
Inline banner
Content
Title
- Tell users what happened or what they can do to fix the problem.
- Try to keep titles to one line.
- Avoid using variables in title text.
Body
- In some cases, users need to know more to solve the problem. In these cases, include body content.
- Add bullet points if needed to improve the scan-ability of the message.
Link
- Add a link if you need to direct customers to a page or a specific action.
- If the solution is too complex, add a link to a help article.
- We do not link to external documentation in our error messages (e.g. Stripe or Adyen documentation). Always look for a Mews guide to link to.
Tone
Match the tone to the severity of the issue. For more details, see Voice and tone
Do
- Use simple words and language to explain the error to users.
- Avoid blaming users for the error.
- Use passive language if it helps to avoid blame or sound less urgent and intimidating.
- Address users with a calm and respectful tone. Use “please”, “thank you” and “sorry” when appropriate, but do not overuse them.
Do not
- Use intimidating, or technical words in error messages.
- Use internal Mews terms.
Specific situations
FinTech and Finance
For payment processing errors, we cannot always show the real reason why an error happened. If a payment is declined for being a fraud or other suspicious behaviours, we need to show guests and properties a general payment error.
To learn more, follow Stripe or Adyen recommendations on specific errors: