Product and UX Content

Error Message Design Sheet

Connect each error to its verified cause, user consequence, prevention, recovery action, preserved data, support path, and accessible implementation.

Free editable Markdown · Content designers, product engineers, and support teams · Updated July 30, 2026

Download Markdown

Accessible HTML preview

Blank template

The downloaded file contains the same fields in editable Markdown.

Error truth

Error ID and surface: [Enter]
User action before error: [Enter]
Trigger and known cause: [Enter]
Causes intentionally indistinguishable: [Enter]
What completed: [Enter]
What failed: [Enter]
Data, payment, or progress state: [Verified]
Security or privacy detail to withhold: [Enter]

Message design

Heading: [What could not happen]
Explanation: [Impact without blame]
Primary recovery action: [Exact label]
Expected result after action: [Enter]
Alternative action: [Enter]
Support path and safe reference: [Enter]
Diagnostic code shown: [Yes / No and reason]
Variable fallback: [Enter]

Prevention and behavior

Can the error be prevented earlier?: [How]
Input preserved: [Yes / No / Partly]
Retry safe and idempotent: [Verified / Not verified]
Repeated failure behavior: [Enter]
Offline or timeout distinction: [Enter]
Session-expiry behavior: [Enter]
Engineering owner: [Name/team]
Support guidance: [Reference]

QA

Tester, build, and date: [Enter]
Recurrence signal: [Metric/support evidence]
Review trigger: [Behavior, incident, support pattern]

Error is announced and associated with the relevant control.
Meaning does not depend on color, icon, or position.
Raw diagnostics and sensitive identifiers are hidden.
Recovery works with keyboard and relevant assistive technology.
Long localized text and variable failures are handled.

How to use this template

Record the trigger, distinguishable cause, completed actions, data state, and security boundary.
Define what the user needs to understand, correct, retry, preserve, or escalate.
Draft a clear problem statement, specific recovery, alternative, and safe support reference.
Trigger and test the error, repeat failure, and successful recovery in the implemented experience.
Monitor recurrence and assign product fixes instead of treating copy as permanent compensation.

Diagnose the state before drafting words

Ask engineering or the responsible system owner what triggered the error, which causes can be distinguished, what action completed, what data was saved, and what the user can safely do. Group causes only when they share the same consequence and recovery. A generic message may be appropriate when the system cannot safely reveal authentication or security details, but its next step must still help. Record internal diagnostics separately from user-facing copy. Codes can support service agents, yet an unexplained code is not a recovery instruction.

Explain problem, impact, and recovery

State what could not happen in language tied to the user's task. Add the consequence they need now: no charge was made, the draft remains saved through a stated point, or the upload was not received—only when product evidence confirms it. Offer one safe primary recovery action and a realistic alternative. Preserve inputs when possible and explain before asking the user to repeat work. Validation messages should name the affected field and acceptable format; system errors should not falsely imply that the user entered something wrong.

Test recurrence and accessible delivery

Trigger the error intentionally in a representative build. Verify focus movement, screen-reader announcement, color independence, link and button labels, keyboard access, narrow layout, localization, and variable fallback. Test retry success, repeated failure, offline transition, timeout, duplicate action, and expired session. Avoid showing raw stack traces, internal URLs, account existence, or private object names. Log repeated error evidence to product and support owners; copy can support recovery, but a frequent preventable failure needs a product fix.

See the fields in context

Fictional example: expired upload session

FileGarden and its session behavior are invented; this is not GPTHuman upload guidance.

Truth: The imaginary session expired before upload began, and the local file never left the device.
Message: “Your session expired before the file uploaded.”
Recovery: “Sign in and choose the file again”; the product cannot safely preserve the file selection.
Alternative: Link to fictional supported-file help without exposing an internal storage path.
QA: Repeated sign-in failure offers support rather than cycling indefinitely.

Frequently asked questions

Should an error message apologize?

An apology can fit the voice, but clarity about the problem and recovery is more important. Avoid repeated empty apologies.

Are error codes useful?

They can help support when paired with understandable guidance and designed not to expose sensitive details.

Should users always be told the technical cause?

No. Explain what matters to recovery. Some technical or security details are uncertain, irrelevant, or unsafe to reveal.

When is copy not the solution?

When the failure can be prevented, recovered automatically, or eliminated through product and engineering changes.