Writing Error Messages People Can Act On
Errors are inevitable. A connection drops, a file is too large, a payment is declined, a setting conflicts with another. What is not inevitable is a bad error message. "Something went wrong" leaves people stuck. "Error 500: undefined index tenant_site_id" leaves them stuck and worried.
The moment an error appears is often the moment someone decides whether to keep trusting a product. So we treat error messages as part of the design, written as carefully as any other text in the product. Here is the approach.
Answer three questions
A useful error message answers three questions in plain language:
- What happened? "Your image could not be uploaded because it is larger than the limit for this field."
- Is anything lost or changed? "Nothing was saved." Or "Your other changes were saved."
- What can I do now? "Choose a smaller image, or compress this one and try again."
When money is involved, the second question matters most. "Your card was not charged" is often the most reassuring sentence in an entire checkout.
Keep technical details out of the way
Error codes, stack traces and server responses help engineers, not customers. They confuse people and can reveal details about our systems that visitors should not see. We keep those details in our logs, where our team can investigate, and show people a plain explanation. When support needs a reference, a short identifier is enough.
Put the message where the problem is
An error should appear next to the thing that caused it. A form field error belongs beside the field. A failed upload belongs beside the upload. A problem with a whole action belongs near the button that started it. Banners at the top of a long page are easy to miss, especially on phones.
Be specific without blaming
Messages describe the situation, not the person. "This email address is already in use on this site" is better than "You entered a duplicate email." Specific, neutral wording helps people fix the problem without feeling scolded.
Distinguish kinds of failure
Different failures need different next steps, so they need different messages:
- Something the person can fix, such as a missing field or a file that is too large
- Something that needs permission, such as a feature not included in their plan or an action their role does not allow
- Something temporary, such as an outside service being unavailable, which may work if retried later
- Something that needs help, where the right step is contacting support
Lumping them together as "an error occurred" removes the information people need to choose the right step.
Never lose what someone typed
The fastest way to turn an error into frustration is to clear a form. When a submission fails, everything the person entered stays in place, with the problem clearly marked. You can read more in accessible forms.
Honest when the outcome is unknown
Sometimes the system does not know whether an action completed, for example when an outside service timed out. The honest message says so: "We are confirming whether this completed. You will not be charged twice." That honesty is part of failing closed.
Consistent wording across the product
The same situation should produce the same message everywhere. If one module says "You do not have permission" and another says "Access denied" and a third says "Forbidden," people wonder whether these are different problems. We keep a consistent vocabulary for common situations, such as permissions, plan limits, unavailable services and validation, so people learn what each message means once.
Test the unhappy paths
It is easy to test only what happens when everything works. We deliberately trigger errors during checks: invalid inputs, oversized files, missing permissions and unavailable services. Reading each resulting message as a customer would is the quickest way to find the ones that need rewriting.
Frequently asked questions
What makes a good error message?
It explains what happened, whether anything was lost or charged and what the person can do next, in plain language near the source of the problem.
Should error messages show error codes?
Technical codes belong in logs. A short reference can help support, but the main message should be plain language.
Why should forms keep entered values after an error?
Clearing a form forces people to start over, which is frustrating and often makes them give up.
Related Posts
Accessible Forms: Labels, Errors and Focus
Forms are where people sign up, pay, register and ask for help. Here is how we make them clear and usable for everyone, including people using screen readers or keyboards.
Brand Colors as Tokens: Keeping Every Customer's Brand Intact
Every organization on our platform has its own look. Here is how theme tokens let each site keep its brand while sharing the same building blocks underneath.
Checking Every Screen at Phone Width
Many people manage their organizations from a phone. Here is why we check every screen at phone width, what usually breaks and how we fix it before customers notice.
Consent First: How We Handle Email and Text Message Permissions
Sending messages people did not ask for damages trust and breaks rules. Here is how our platform treats consent, unsubscribes and suppression as features, not fine print.
Writing Code the Next Person Can Understand
Code is read far more often than it is written. Here are the habits we use to keep it clear for the next developer or AI assistant who has to change it.
Comments (0)
No comments yet. Be the first to share your thoughts!