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.
Address not found
Something’s not right
Please make sure your address information is correct.
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.
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.
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.
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.
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
Check your internet connection
You’re not connected to the internet right now. Check your connection and refresh. [Refresh]
Network connection error
This operation could not be completed because the server connection has failed. Please check your network settings.
Having trouble with your password? We can help you reset it. [Reset password]
Your credentials are invalid. Please try again.
We couldn’t undo one or more transactions
We need to fix some things on our end. Give us a moment, then try again.
We couldn’t undo the transaction(s) due to an invalid resolved entity. Try again later.
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.
Update your billing profile before adding or editing data.
[Update billing profile]
You cannot add or edit data until you update your billing profile which can be accessed from the settings menu in your client list.
Resubscribe to make changes
If you want to make changes to your account info, resubscribe to QuickBooks Online.
For your information
Sorry, you can’t add data because your QuickBooks subscription isn’t active. Please update your subscription or contact your administrator.
Select a different type of account
Go to App settings to select a different type of account for this transaction. Then try again.
We couldn’t add the transaction(s) because you need to check your account details before you continue. You may need to select a different type of account for your transaction(s). Try again later.
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.
Your subscription payment didn’t go through. Update your billing info to e-file 1099s.
Your subscription is restricted due to a payment failure. Update your billing info to avoid suspension of your account. While your account is restricted, you can’t e-file 1099s.
Sign in to continue.
You have not been logged in.
We don’t currently offer upgrades for annual subscriptions
Your current subscription is on annual billing.
[Cancel][Switch to monthly billing]
You don’t meet the eligibility requirements for upgrading.
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.
Your role doesn’t have access to this
To view this, ask your account admin to change your permissions.
You don’t have access rights to view this data.
It’s time to update your browser
To keep using QuickBooks, update or switch to a browser we support by Feb 1, 2021.
[Find a supported browser]
Hmm…something isn’t right
QuickBooks is no longer supported on this browser.
Update your billing info
We couldn’t process your payment. Update your billing info by 3/22/2022 to resume your subscriptions and keep the same pricing.
Your subscriptions were suspended because we couldn’t process your payment. Want to keep your pricing and resume your plans? [Resume now]
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
Your role changed
You were signed out because your QuickBooks admin changed your role. Sign in again to keep using QuickBooks.
You don’t have sufficient permissions
Your account administrator changed your role and caused you to be signed out. Sign in again to proceed.
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
Update your payment method
Your card on file has expired. To keep using QuickBooks Online, update your payment method.
[Cancel] [Update payment method]
Your subscription is delinquent
Your credit card on file has expired. Update this immediately to avoid suspension of your account.
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:
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.
- Someone enters the wrong password
- No internet connection
- The credit card on file is expired
You’re already subscribed
No need to subscribe again—you’re all set.
We couldn’t turn off this setting
Give us a moment to catch up when turning settings on and off. Then try again.
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.
- 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
Our info is out of sync
We need to fix some things on our end. Sign out, and try again later.
Something isn’t working
We’re sorry. We ran into an issue on our end and need to reload your data. It could take a minute or two.
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.
- Failure of an application resulting in data loss
- Payment failure due to suspected fraud
Your payment didn’t go through
Try a different payment method, or contact your bank or card issuer for more information.
We’ve experienced an issue
Please contact us at 1-800-555-5555 so we can walk you through next steps.
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.
- 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:
- More info (optional)
- Call to action
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.
This sales channel is already connected
This channel is already up and running. Connect another channel, or return to Overview.
[Connect another channel] [Return to overview]
Call your card issuer
For your security, call your card issuer to authorize this purchase.
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.
Wells Fargo sent you this message about the info you tried to import:
[The content from Wells Fargo appears here.]