Error state
Design assets pendingPeer review pending
An error state notifies a user that something went wrong.
// import one of the following ingredients for the error state pattern
import {Alert} from '@twilio-paste/core/alert';
import {Callout} from '@twilio-paste/core/callout';
import {Toast} from '@twilio-paste/core/toast';
import {HelpText} from '@twilio-paste/core/help-text';
Use an error state after a problem occurs. For example:
- A user tried to submit a form with required fields missing.
- A failed connection terminates a user action.
To proactively call a user’s attention to information that can help them avoid errors or undesirable outcomes, use a warning. For example:
- Telling a user an action might increase their bill.
- Telling a user they’re about to hit a limit.
- Telling a user a selection has notable limitations.
- Telling a user an action could result in lost data.
When developing an error message:
- Tell the user what happened, why it happened, and how to fix it (if they can).
- If you’re tight on space, prioritize what happened and how to fix it.
- If you have extra room, explain what happens if the error isn’t fixed.
- Be as specific as possible. Develop a tailored error message for each possible cause.
- Use plain, human-readable language. Prioritize active voice, but consider passive voice when the emphasis should be on the outcome and not who/what caused the outcome.
- Avoid blaming the user. Focus on what the user needs to do to move forward, not what they did not do.
- Avoid certain words. The language we use during an undesirable experience matters. Avoid the
following language:
- Technical jargon. Don’t introduce terms your users may not understand.
- Negative or alarmist words like: forbidden, illegal, prohibited, valid/invalid.
- “Please.” It makes the action sound optional.
- “Sorry.” Overusing it makes it lose its meaning. Reserve this for situations where something highly detrimental has happened, like lost data.
- Place the error message as close to the source of the error as possible.
When possible, use an icon and color to indicate an error. When using only an icon or color, ensure the content clearly indicates something went wrong.
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| We don’t know what happened and there are many possible causes | Something went wrong. Try again later. Something went wrong. Contact customer support. Something went wrong. Try again later. If the problem persists, contact customer support. | Don’t use “Something went wrong” if we can tell them specifically what went wrong. Don’t include “Try again later.” if we don’t think that could help the situation.’ If we can’t pinpoint the issue but we know that the user cannot solve the issue on their own, include language around customer support. Only include a directive to contact support if you’ve confirmed with the customer success team that it’s OK, and there’s a reasonable chance that they could help with the possible underlying problems. |
| Data retrieval error | The [data type] could not be loaded. Try reloading the page. If the problem persists, contact customer support. | Only include a directive to contact support if you’ve confirmed with the customer success team that it’s OK, and there’s a reasonable chance that they could help with the possible underlying problems. |
| Another service is down | [Service] could not be reached. Check [website] for more information. | Link to a status page if available. For example, https://status.twilio.com/. |
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| Internet connection problem | Internet connection failed. Check your connection, then try again. | |
| Request timeout | Server connection failed. Try again later. |
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| Required fields | Enter [thing]. | |
| Required selection fields | Select [thing]. Select at least [#] thing(s). | |
| Character limits | [Thing] is too long. [Thing] must be [#] characters or fewer. [Thing] is too short. [Thing] must be at least [#] characters. [Thing] must be between [#] and [#] characters. | If we can, tell them how many characters over the limit they are. |
| Character types | [Thing] cannot include [character type]. [Thing] can only include [character types]. | |
| Format validation | Enter [thing] in this format: [example]. | When possible, standardize formatting on the backend instead of forcing users to use precise formatting standards. |
| Value limits | Too many [things]. You can enter up to [#] [things]. | |
| Duplication of value | [Thing] already exists. Enter a different [thing]. | |
| Multiple missing required values in a section | Enter values for all fields. |
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| Access authorization | You do not have access to [thing]. Contact your workspace admin. You do not have permission to [thing]. Contact your workspace admin. | |
| Authentication | [Thing] could not be authenticated. Check the [type of credential], then try again. |
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| Setting not enabled | To [action], enable [setting]. | |
| Connection missing | To [action], connect [thing]. |
| Type | Recommended phrasing(s) | Notes |
|---|---|---|
| Something didn’t send | [Thing] did not send. Check [some things], then try again. | Don’t include “Try again later.” if we don’t think that could help the situation. |
Work with engineers to try to avoid an endless “try again” loop. Explore whether you can offer a series of things to check if the user hits a particular error several times in a row.
Include error codes only when the user can use it to troubleshoot by themselves or by giving the code to customer support. Ensure there is either public documentation or support team documentation that maps error codes to specific resolution instructions before including error codes.
Place error codes at the end of the message inside parentheses.
An empty state is also an error state when content fails to load. Error empty states can result from problems like a system issue or access issue. Error empty states are different from empty states that result from a lack of data to show. If the error empty state occurs in a small component (a card, for example), prioritize communicating how to fix the problem.
When cards are used as part of a dashboard to display metrics, error states can occur on individual cards because the data populating a particular card isn’t available. Since these cards are usually small, use error iconography paired with a 3-5 word error message.
Please update your billing information or we'll suspend your account on March 2. We couldn't renew your subscription with the information we currently have. Update billing information
- Alerts communicate a critical issue at the system level, like site-wide service disruptions, active incidents, or expired billing information.
- Alert error messages do not result from a user action.
(error)
Missing information
Enter values for all required fields.
- Callouts communicate:
- An error specific to a particular section of a page, or that applies to a whole page.
- An error summary of multiple errors on the page. When used for form validation, still include the inline error messages.
- Use Callouts for situations like operation failures with multiple pieces of information, or a form submission missing many required fields.
- Callout error messages can result from a user action, but don’t have to.
There was an error when deleting the profile. Please try again.
- Toasts communicate brief, easily comprehended error messages that are not the user’s fault, like a failed connection.
- Toast error messages usually result from a user action.
- Toast error messages should never automatically disappear.
Enter a valid email. Use your work email address.
- Help Text communicates contextual errors, like field validation.
- Help Text can result from a user action, but doesn’t have to.
- Alert
- Badge
- Singleselect Combobox
- Multiselect Combobox
- Date picker
- Disclosure
- File picker
- File uploader
- Form
- Form pill group
- Help text
- Input
- Radio button group
- Radio group
- Select
- Textarea
- Time picker
- Toast
Enter a phone number.
Do
Focus on what the user can do to fix the issue.
You did not enter a phone number.
Don't
Avoid phrasing error messages in a way that blames the user.
The connection was lost.
Do
Use passive voice when the outcome is most important.
Our servers lost the connection.
Don't
Avoid prioritizing active voice when it’s more important that the user knows what happened, not who did it.
Your password must contain at least 8 characters.
Your password cannot have spaces.
Do
Use individual error messages for different validations.
Your password might be too long, too short, have spaces, or lack a number or special character.
Don't
Don’t combine possible error causes if we can validate against each one.
Your password must contain at least 8 characters.
Your password cannot include special characters.
Do
Show all relevant validation error messages at once, so the user doesn’t hit multiple errors in a row.
Your password must contain at least 8 characters.
Your password cannot include special characters.
Don't
If there are multiple validation errors, don’t make the user fix each one individually.
Name cannot contain special characters. Use only letters and numbers.
Do
Use plain language to explain what went wrong.
Name is invalid. You entered an illegal character.
Don't
Don’t use scary or negative words.
(error)
Something went wrong. Contact customer support. (Error code: 6789)
Do
Include error codes in parentheses at the end of the message only when the user can use it to troubleshoot by themselves or by giving the code to customer support.
(error)
Error: Code 6789: Something went wrong. Contact customer support.
Don't
Don’t start error messages with “Error” or the error code.