Write error messages

Outcome

An error inventory for one flow: every failure the flow can produce, each with a message that says what happened and what to do, where it appears, and who reviewed it. The messages are in the product's voice and readable by someone who has never seen the code.

When to use it

• A flow is being built or redesigned and its error states have not been written yet.
• Support tickets quote error messages back at you, or people abandon a flow at the same error.
• Error copy in a product was written by whoever wrote the code, one message at a time.

When not to use it

• The error could be prevented by the design, such as a date picker that allows impossible dates. Fix the design first; see error prevention.
• The failure is a system outage the user cannot act on. That needs a status page and an incident message, not form copy.
• You need product-wide voice and tone rules. Agree those first; this procedure applies them to one flow.

Before you start

• The flow. Screens or a prototype of one flow, such as sign-up or checkout.
• The failures. A list from the engineers of what the system can reject and why, including server-side checks.
• The voice. Any existing tone guidance or a few messages the team considers good.
• A reviewer. An engineer who can confirm each message describes the real cause.

Steps

Step 1: List every way the flow can fail

Go through the flow field by field and action by action with an engineer. For each, list what the system rejects: empty, wrong format, too long, already taken, expired, not allowed, timed out, payment declined. Include failures the person cannot see coming, such as a session expiring.

You should now have: an inventory of every failure in the flow, each with its real cause.

Step 2: Remove the errors the design can prevent

For each failure, ask whether the interface could stop it from happening: constraints on input, sensible defaults, accepting more formats, confirming before a destructive action. Move those to a design list and take them out of the inventory.

You should now have: a shorter inventory of errors that need a message, and a design list of errors to prevent.

Step 3: Write what happened, in plain words

For each remaining error, write one sentence saying what went wrong from the person's point of view, such as this email is already linked to an account. No codes, no "invalid", no "error occurred", and no blame.

You should now have: one plain sentence per error describing what happened.

Step 4: Add what to do next

Add the action that fixes it, as specifically as you can: the format expected, the limit, the button to press, or a link to the next step, such as sign in instead or use a different email. If the person cannot fix it, say what will happen and when.

You should now have: every message stating what happened and what to do next.

Step 5: Decide where each message appears and when

Place each message next to the field or action it is about, and show it when the person leaves the field or submits, not while they are still typing. Do not clear what they entered. Make sure it is announced to screen readers and that colour is not the only signal.

You should now have: a placement and a timing for each message, with what the person typed kept.

Step 6: Edit for length and tone

Read every message aloud. Cut words that add nothing, keep each under about two short sentences, and remove apologies and jokes from errors that cost the person something, such as a declined payment. Use the same words the interface uses for the same things.

You should now have: messages that are short, consistent with the interface and calm in tone.

Step 7: Review with an engineer and test the worst one

Have the engineer confirm each message describes the real cause, because a message that blames the wrong thing sends people the wrong way. Then show the message for the most common failure to two or three people who have not seen the flow and ask what they would do next.

You should now have: a reviewed inventory, with the most common message checked by people outside the team.

Worked example

A team rewrites the error states of a sign-up form whose old messages were all "Invalid input".

1. The inventory has eleven failures, including an empty name, a malformed email, an email already registered, a password under 12 characters, and a verification link that has expired.
2. Two are prevented by design: the phone field accepts spaces and brackets instead of rejecting them, and the country field becomes a list.
3. For the registered email, the sentence becomes This email is already linked to an account.
4. The action is added: Sign in instead, or use a different email. with sign in linked. For the expired link: This link has expired. We've sent a new one to ana@example.com.
5. Every message moves next to its field and appears when the person leaves the field, and the password field keeps what was typed.
6. Oops! Something went wrong with your password :( becomes Use at least 12 characters.
7. The engineer finds that "already linked" also fires for accounts deleted in the last 30 days and asks for a separate message. Three people shown the registered-email message all say they would sign in.

Checklist

• Every failure in the flow is listed with its real cause.
• Errors the design could prevent were moved to a design list.
• Each message says what happened, without codes or blame.
• Each message says what to do next, or what will happen if nothing can be done.
• Each message sits next to the field or action it is about.
• What the person typed is kept after an error.
• Messages are announced to screen readers and not signalled by colour alone.
• An engineer confirmed every message matches its cause.

Common mistakes

• One message for many causes. "Something went wrong" leaves people guessing between a typo, a taken name and an outage.
• Blaming the person. "You entered an invalid email" adds blame and no information. Say what the system needs.
• Messages far from the problem. A banner at the top of a long form makes people search for the field.
• Humour in a costly moment. A joke on a declined payment reads as not taking the problem seriously.
• Writing errors last. Messages written after the build are written by whoever is closing the ticket.

Related

• AI Microcopy Generator: draft variants for an error message from a short brief, then edit them against this procedure.
• Help users recognize, diagnose and recover from errors: the heuristic every message serves.
• Error prevention: the design list from Step 2.
• UX writing fundamentals course: interface writing in lessons with knowledge checks.