Error Message Vocabulary

The three-part error message framework — what happened, why it happened, and what to do next — is the gold standard for user-facing errors: it respects the user's time by giving them enough to act, not just enough to know something went wrong.

Error message UX writing principles: (1) Describe the problem in plain language — "You don't have permission" not "403 Forbidden"; (2) Avoid blaming the user — "The file couldn't be uploaded" not "You uploaded the wrong file type"; (3) Provide a recovery action when possible — "Contact your admin to request access" gives the user a clear next step; (4) Be specific about what went wrong — "The file must be under 5MB" is more useful than "Upload failed"; (5) Match the tone of the product — a playful consumer app can use informal language; an enterprise tool should stay professional. The HTTP status code can be included (for support escalation) but should be secondary to the plain-language explanation.

Key vocabulary:
• error message — text displayed when something goes wrong, explaining the problem and ideally offering a recovery path
• recovery action — a specific, actionable next step provided in an error message to help the user resolve the problem
• plain language — writing that uses common words and clear sentence structure, accessible to users without technical expertise

Leaking technical error codes into user interfaces is both a UX failure (meaningless to users) and a security concern (reveals implementation details to potential attackers).

"NullPointerException" or "Object reference not set to an instance of an object" tells a security-conscious attacker that: (a) the application is written in C# or .NET; (b) there's a null-check missing somewhere; (c) the error wasn't caught by the error handling layer (suggesting fragile error handling). Attackers can use this to probe for similar unhandled exceptions. From the user's perspective, the message provides: zero information about what they were trying to do that failed, zero information about whether this is a temporary or permanent problem, and zero information about what to try next. The correct approach: catch exceptions at the application boundary, log the technical details (for engineering debugging), and show the user a human-readable message explaining the functional impact.

Key vocabulary:
• technical error code — a system-level identifier (exception class name, numeric code) that describes the implementation error rather than the user impact
• error handling layer — the application code responsible for catching exceptions and converting them into appropriate user-facing messages
• information leakage — unintended exposure of system implementation details through error messages, logs, or API responses

"Something went wrong" is the UX equivalent of a blank page — it tells the user the system failed but leaves them completely without guidance, forcing them to guess what to try next or abandon the task entirely.

Specific error messages require engineering effort: the application must catch different error types and surface appropriate messages for each. This is why vague messages proliferate — "something went wrong" is the lazy fallback for unhandled cases. Good error message systems include: a library of specific messages for common failure modes, a tiered approach (specific message if known, helpful generic if unknown), and a feedback mechanism ("Was this helpful?" or a link to report the error). A/B testing of error messages is legitimate UX practice: Duolingo and other consumer apps have data showing specific error messages significantly improve recovery rates compared to vague alternatives.

Key vocabulary:
• vague error message — a non-specific message that doesn't describe the problem or provide recovery guidance
• error message specificity — the degree to which an error message describes the actual problem and provides actionable next steps
• recovery rate — the percentage of users who successfully complete a task after encountering an error

Recovery actions transform error messages from dead ends into paths forward — they are the difference between a user who abandons in frustration and one who successfully completes their task.

Recovery action design principles: (1) Match the action to the problem — a transient error gets "Try again"; a validation error gets "Fix the highlighted fields"; a permission error gets "Request access from your admin"; (2) Make the action a button or link, not just text — "Contact support at support@company.com" is better as a "Contact support" button that opens a pre-filled email; (3) If the error requires technical investigation, give the user a reference number — "Error ID: ABC-12345" allows support staff to correlate with logs; (4) Test that the recovery action actually works — a "Try again" button that doesn't retry the action is worse than no button. The Mailchimp UX writing guide is a classic reference for recovery action patterns.

Key vocabulary:
• recovery action — a specific instruction or interactive element in an error message that helps the user resolve the problem
• error ID / reference number — a unique identifier in an error message that allows support teams to locate the corresponding error log
• transient error — a temporary error (network timeout, server overload) that may resolve if the user retries

A/B testing error messages is legitimate and valuable — the best error message is the one that leads to the highest task completion rate, and data is the most reliable way to find it rather than relying on UX intuition alone.

Practical example: a team testing a payment error message tries two versions — "Payment failed. Please try again." (Version A) vs. "Your card was declined. Check that your card number, expiry date, and CVV are correct, then try again." (Version B). Measuring recovery rate (users who successfully pay after seeing the error), Version B might show 25% higher recovery because it tells users specifically what to check. The support contact rate might also drop for Version B — fewer users need to call support because the message explains the problem. High-frequency errors like form validation errors, payment errors, and login errors are the best candidates for A/B testing because they have sufficient volume. Error messages for rare system failures typically don't have enough volume for statistical significance.

Key vocabulary:
• A/B test — a controlled experiment showing different versions to different user segments to determine which performs better on a measured outcome
• recovery rate — the percentage of users who complete the intended action after encountering an error
• statistical significance — the confidence level that observed differences between test variants are real, not due to random variation