The Error Message Audit

The problem

Error messages are the most-seen, least-loved copy in any product. Our platform had accumulated 200+ unique error messages over five years of development — written by engineers, PMs, and the occasional content person, with no shared standards. The result was a mess of tones, formats, and levels of helpfulness.

Engineering flagged it as a problem when they started internationalising the product. Translating 200 inconsistent strings was expensive. But the bigger issue was user trust: bad error messages erode confidence in a product.

Discovery

I spent two weeks cataloguing every error message in the product, tagging each by:

• Author (engineering, PM, content, unknown)
• Tone (helpful, neutral, alarming, blaming)
• Format (sentence, code string, all-caps, mixed)
• Actionability (tells user what to do, doesn't tell user what to do)

The findings were stark. Only 31% of error messages told users what to do next. 18% used technical jargon from the stack. Several actively blamed the user ("You entered an invalid value"). One said only: ERR_502.

I also looked at the emotional register. Errors are already stressful — the last thing a user needs is a message that makes them feel stupid or scared. Our messages were failing this test repeatedly.

Framework

I designed a three-part error message framework:

1. What happened (plain language, no jargon, no blame) 2. Why it happened (when useful and knowable) 3. What to do next (specific, actionable, or a way out)

Each part maps to a sentence. Short errors can collapse all three into one. Longer errors (like authentication failures) can expand them.

I also defined four error categories with distinct tone guidance:

• User errors — gentle, non-blaming, action-focused
• System errors — honest about the issue, apologetic when appropriate
• Validation errors — precise, instant, inline
• Catastrophic errors — calm, clear, with a human escalation path

Applying it

I didn't rewrite all 200 messages myself — that would have been slow and wouldn't have built organisational knowledge. Instead I:

1. Ran a half-day workshop with the 4 product squads most affected
2. Rewrote 30 high-traffic examples as worked examples
3. Created a Notion template squads could use to self-review messages
4. Added an "Error Messages" section to our content style guide

The worked examples became the backbone of the framework doc. Engineers could copy-paste the structure; designers could gut-check against the principles.

Outcome

Six months post-launch of the framework:

• New error messages reviewed against framework: 94% (up from ad hoc)
• Internationalisation cost per string: down 28% (fewer long, complex messages)
• "Confusing error" NPS verbatims: down 40% in post-release surveys
• Engineering team described the framework as "the best thing content has shipped this year" — which is either high praise or a reflection of how bad things were before

The framework is now part of new engineer onboarding.