An error occurs after a user takes an action but, either the expected result doesn’t happen — or nothing happens. (If you need to communicate potential issues before a user takes action, use a warning. Components that include warnings statuses are Banner, Callout, and Toast.)
Errors can cause frustration, confusion, data loss, or rework for users. Error messages are one of the most important content elements in our UI and one of the 5 quality components of usable experiences.
Design to prevent errors
Before you write error messages, try to prevent errors from occurring in the first place. Partner with your engineers and PM to understand possible error states and try to find ways to avoid the error altogether by guiding users with:
- Visual cues: Help users understand when and where they need to make a selection or entry. For example, identify optional fields.
- Disabled states or deactivated controls: Prevent users from submitting incomplete information that will trigger errors. For example, deactivate the primary action button on the page until all required information has been provided.
- In-line validation: Display an error as soon as users have finished filling out a field, without users needing to submit the field. After the field has an error, remove the error state once their input is valid. Use inline validation whenever possible. See Text field.
Make error messages clear and useful
Good error messages answer two questions as clearly and concisely as possible:
- What went wrong.
- How to fix the problem.
- If there’s no solution, suggest next steps if possible: Try again later. or Contact support for help.
How to write error messages
Be specific
Create unique, specific error messages that tell users how to solve the error. Don’t rely on repeating a default message.
Be concise
Give users only the information they need to solve errors. Generally, error messages are the least conversational UI content.
Use general language
It’s usually unnecessary to include filenames, usernames, or other specifics. Use general terms that can cover the most use cases and be localized more easily.
Use language that all users can understand
Include technical terms only when the detail helps solve the error and the users will understand them. For product errors, this includes removing or minimizing the use of error codes.
Use consistent language
Repeat the same vocabulary as the feature, the screen, and the component for clarity. In UI content, repetition helps build a user’s mental model and maintain clarity. Using synonyms for variety can confuse users.
Be supportive
Give users the information they need to correct errors, especially if errors are complex. This will reduce user frustration and rebuild their trust when using the product.
Don’t blame the user
Users should feel encouraged to take action to correct the issue rather than blamed for causing it. Avoid blame by not using you when explaining the error or using passive voice if needed.
Don’t be overly polite or apologetic
Avoid using please and sorry unless the error was caused by Okta and has severe consequences, such as requiring rework.
- Saying sorry in error messages can make the situation worse by causing errors to appear more severe.
- Similarly, saying please could make users think a required action is optional. And, saying please repeatedly makes attempts at politeness arbitrary and potentially insincere.
Don’t use humor
Errors are a negative experience for users. Humor can cause frustration, be misinterpreted or delay users fixing the error. In Okta products, never use Oops! or Uh-oh.
Generic errors
Sometimes errors have so many potential causes or are so major, we can’t clearly and concisely provide details. In these cases, users have no way to understand what went wrong or how to fix it.
In these cases, use a generic error.
Errors when a page or system is unavailable
Use these generic errors when:
- A server error is preventing an entire page from being displayed, like with 400- or 500-series server errors.
Error message types and components
Inline error
Inline errors are concise, in-context errors that tell users what went wrong with an input or group of inputs and how to fix it.
There are generally three types of inline error messages:
- The user didn’t include information that was required. The default format for this kind of error is: Enter {your/the/a} {field label}, such as Enter your name. or Enter a group.
- The information didn’t pass validation. The text should be actionable and explain to the user what they need to do to proceed. For example: Enter a complete email address, such as you@okta.com.
- The information can’t be saved due to a product error. The text should explain what happened and prompt the user to try again. For example: There was a problem {validating your input/saving your entry}. Please try again.
Inline errors are the most frequent type and occur in these components:
Banner
An error banner should be used:
- When you have system-wide error messages that require user attention.
- When you need an error displayed according to the system settings (this could be a single view, a time period, or until an action is completed).
- When you have multiple inline errors in a form and need an overarching banner to summarize them and drive users to fix them.
See Banner
Callout
An error callout should be used:
- When the error is confined to a specific area in the UI.
- When the error needs to persist until it is fixed or dismissed by the user.
- When you need the alert to be in context of a specific area.
See Callout
Toast
An error toast should be used:
- When the error is noncritical.
- When you need to immediately confirm a user’s action failed.
See Toast
Empty states
Two of the three empty state variants are errors.
A system error empty state:
- Tells users when there is data but it can’t be surfaced due to a lack of proper permissions, configurations, or other reasons.
- Explain the problem and tell the user what action to take to correct the issue and populate or access the data.
An user action empty state:
- Explains why the data is unavailable and what the user can do, if anything, to display the data.
See Empty states
Have questions or need support?
Oktanauts can use the following resources when building with Odyssey:
- Check the Odyssey 1.0 FAQs.
- Join #odyssey in Slack and tag @content to ask questions.
- Attend Odyssey Office Hours on Mondays and Wednesdays from 1-1:30 p.m. PT / 4-4:30 p.m. ET.
- Submit bug reports and feature requests to the Odyssey Jira board.