Skip to content
UX Atlas
Plate WRT·002 · UX writingGrid F2 · Rev. 2026-08-14

Error Messages

Say what happened, why if you know, and what to do next, in that order and in plain language.

UX writingExpert heuristicFoundational

Definition

An error message explains a failed operation and offers a route forward. Its quality determines whether a failure becomes a recovered task or an abandoned session.

Expert heuristic. A review criterion developed by practitioners. Useful and widely taught, but evaluated by judgement rather than measurement.

On this plate
  1. 1Definition
  2. 2Writing them
  3. 3Placement and semantics
  4. 4What each part of the message does
  5. 5In practice
  6. 6Commonly confused with
  7. 7Local chart
  8. 8Continue from here

Reach for this when

  • Any failure state.
  • Form validation.
  • Reviewing support tickets caused by unclear failures.

Common mistakes

  • Generic messages.
  • Technical detail leaked to users.
  • Errors far from their cause.
  • Blame in the wording.
  • Writing the message from the system's point of view, which produces accurate sentences the reader cannot act on.

Writing them

Do

  • Name the specific problem: 'This email address is already registered'.
  • Offer the action inline: a sign-in link, a retry button, a way to change the value.
  • Use plain words: declined, expired, unavailable, too large.
  • Say what is preserved: 'Your draft is saved'.
  • Match the tone to the severity. Data loss is not the moment for humour.

Do not

  • Show status codes or exception text to users.
  • Blame: invalid, illegal, incorrect, you failed to.
  • Use humour for serious failures.
  • Say 'please try again later' with no explanation and no estimate.

Placement and semantics

  • Next to the field or element that caused it.
  • Associated with the field through aria-describedby, with aria-invalid set.
  • Summarised at the top of long forms, with links to each field and focus moved to the summary on submit.
  • Never colour alone: include an icon and text.
  • Never in a toast if the user has to act on it.

What each part of the message does

PartJobFailure without it
What happenedName the failure in the reader's termsThe reader does not know what is wrong
Why, when knownGive the cause they can act onThey guess, usually incorrectly
What to doOne concrete next stepThey retry the same thing and fail again
What was not lostReassure about stateDuplicate submissions and duplicate charges
Where to goA route out for the unfixableThe session ends here

In practice

  1. i.

    Your card has not been charged

    Saying what did not happen

    A payment failure message that states no charge was made prevents a second attempt, a duplicate charge and a support ticket. It is one sentence and it does more work than the retry button.

Commonly confused with

Close neighbours that get substituted for each other. The difference is stated first, then the condition that picks one over the other.

vs.

Error Identification and Suggestion

Accessibility

The requirement that errors are named in text, located, and offered a correction.

Key difference

Error identification is the mechanism: the failure is stated in text, tied to the field and announced. Error messages are the sentence itself. A perfectly wired error that says Invalid input still leaves the reader stuck.

Use Error Messages when

  • The error is detected and announced but says nothing useful.
  • The wording blames the reader or names an internal code.
  • The fix is what happened, why, and the next step, in that order.

Use Error Identification and Suggestion when

  • The error is conveyed by a red border alone.
  • Nothing is announced, or focus never reaches the problem.
  • You are checking against WCAG 3.3.1 and 3.3.3.

Learn about Error Identification and Suggestion

Local chart

WRT·002 · Region III · Grid F2

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Framing EffectBIAS·003 · PRINCIPLES BEHIND THISError PreventionHEUR·005 · PRINCIPLES BEHIND THISHelp Users Recognise, Diagnose and Recover From ErrorsHEUR·009 · PRINCIPLES BEHIND THISMatch Between System and the Real WorldHEUR·002 · PRINCIPLES BEHIND THISVisibility of System StatusHEUR·001 · PRINCIPLES BEHIND THISPostel's LawLAW·012 · PRINCIPLES BEHIND THISInput ValidationPAT·007 · RELIED ON BYError Identification and SuggestionA11Y·016 · COMMONLY CONFUSED WITHForm UX ChecklistCHK·001 · CHECK YOUR WORKMicrocopyTERM·132 · SHORT DEFINITIONVoice and ToneTERM·133 · SHORT DEFINITIONUse of ColorA11Y·010 · RELATED CONCEPT

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Applies when you are designing

A CheckoutA FormA Mobile AppAn AI ProductAn Ecommerce ExperienceAn Enterprise WorkflowAuthentication

Principles behind this

The reasoning this solution is an application of.

Relied on by

Entries that assume this is already in place.

  • Input ValidationPAT·007 · Pattern

    Detecting the problem is half the job. The sentence is the other half.

Check your work

Review passes that test whether this was done properly.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.