How Should You Design Error Messages in a SaaS App?

How should you design error messages in a SaaS app?

Write them where the problem is, in plain language, describing what went wrong and what to do next, without blaming the user or losing their work. That is the whole job. It sounds obvious and almost no product does it consistently, because error copy is owned by nobody.

Every product team we have worked with has a design system for buttons and no system at all for failure states. The result is a product whose best moments are carefully designed and whose worst moments are improvised by whoever wrote the validation.

Here is a framework for fixing that, built on guidance that has been tested rather than invented.

Why do error messages deserve their own system?

Because they are read more carefully than almost anything else in your interface. A user skimming a dashboard is browsing. A user reading an error is stuck, frustrated and paying full attention. Every word lands harder.

They are also the moment your product is most likely to be abandoned. Nobody churns because a button was the wrong shade. Plenty of people give up because they could not work out why a form would not submit.

And the failure is systemic rather than individual. When there is no shared standard, every engineer writes their own message in their own voice, and the product ends up speaking with fifty voices in its worst moments.

What does the established guidance actually say?

Nielsen Norman Group's error message guidelines, published on 14 May 2023, group the rules into four sets. On visibility: display errors close to the source, use noticeable, redundant and accessible indicators, design errors based on their impact, and avoid prematurely displaying errors.

On communication: use human-readable language, concisely and precisely describe the issue, offer constructive advice, and take a positive tone without blaming the user. On efficiency: safeguard against likely mistakes, preserve the user's input, reduce error-correction effort, and concisely educate on how the system works.

These sit under Jakob Nielsen's ninth usability heuristic, originally published on 24 April 1994 and last reviewed on 30 January 2024, which states that error messages "should be expressed in plain language (no error codes), precisely indicate the problem, and constructively suggest a solution."

What is the single highest-leverage rule?

Prevent the error instead. Nielsen's fifth heuristic is explicit: "Good error messages are important, but the best designs carefully prevent problems from occurring in the first place." The best error message is the one that never appears.

In practice that means constraining input rather than validating it after the fact. A date picker prevents an invalid date. A disabled submit button with a clear reason prevents a failed submit. A field that accepts several formats prevents a format error.

Run this test on your top five errors by volume: could the interface have made this impossible? For most products, at least two of the five are preventable by design rather than by better copy. Our notes on form design cover the mechanics.

What does accessibility actually require?

Two things, and they are separate. WCAG 2.2 Success Criterion 3.3.1 Error Identification covers notifying the user that an error occurred. Success Criterion 3.3.3 Error Suggestion, at conformance level AA, goes further.

Its text is precise: "If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content." So if you know how to fix it, you have to say so.

The intent section explains who this protects. People with cognitive disabilities may struggle to work out how to fix an error, and people with visual impairments may not be able to determine the correction method. W3C notes that providing correction guidance makes users less likely to abandon forms, which is the same outcome your conversion metrics care about.

What should every error message contain?

Three parts, in this order. What happened, stated plainly. Why it happened, if you know and if it helps. What to do next, as a specific action rather than a suggestion to try again.

A fourth part is optional and valuable for serious failures: a reference the user can give to support. Not as the whole message, and never instead of plain language, but tucked below it. Nielsen's heuristic rules out error codes as the message; it does not rule out an identifier alongside a human explanation.

What should never appear: the word "invalid" with no explanation, a raw exception, a stack trace, or any sentence that begins by telling the user what they did wrong. The last one is a tone problem that costs you goodwill for no benefit.

How should errors differ by severity?

Match the interruption to the cost. Nielsen Norman Group's guidance to "design errors based on their impact" is the rule here, and most products get it backwards by using the same treatment for everything.

A field-level validation belongs inline, next to the field, quiet. A failed save belongs in a persistent banner that does not disappear on its own. A destructive failure, such as a payment that did not go through, belongs in something the user has to acknowledge.

Getting this wrong in either direction is costly. A modal for a mistyped email is insulting. A toast that vanishes after four seconds for a failed data import means the user never learns their data is missing. Our piece on SaaS notification design covers where each pattern belongs.

How do you handle the errors you cannot explain?

Honestly, and with a path forward. Some failures genuinely are unknown at the interface layer: an upstream service timed out, something went wrong in a way nobody anticipated. Pretending otherwise produces messages that are confidently wrong.

The pattern that works is to say that something failed, say what state the user's work is in, and give them one action. "We could not save your changes. Your work is still here. Try again, or contact us and quote this reference." That is honest and it is useful.

Nielsen Norman Group's guidance includes one further note for the worst cases: "mitigate total failure with novelty." A well-designed empty-handed error page is better than a blank screen, as long as the novelty does not replace the information.

How do you build this into a system?

Write a short standard, not a long one. Four rules that fit on a card get followed. A twenty-page tone-of-voice document does not. Ours would be: say what happened, say what to do, never blame, never lose their input.

Then put the messages somewhere they can be reviewed. If error strings live scattered through the codebase, nobody ever reads them together, and inconsistency is guaranteed. Centralising them makes a quarterly review possible, which is when you notice that three features say three different things about the same failure.

Finally, instrument them. Count how often each error fires. The top five by volume are your real design backlog, and they are almost never the ones the team assumed. Our notes on SaaS dashboard UX touch on the same measurement habit.

What should you do this week?

Pull your ten most frequent error messages and read them out loud. Reading aloud catches blame, jargon and vagueness faster than any review process. Then rewrite them against the three-part structure and ship the copy change.

It is one of the very few product improvements that costs almost nothing, needs no new component, and is felt immediately by the users having the worst day with your product.

If you want help building a real standard for this, or a second pair of eyes on your current failure states, we are happy to walk through it. Find us at phoenix.studio.