Well-crafted error messages help users understand what went wrong and how to fix it — reducing frustration and support requests. This guide sets standards for writing clear, consistent, and empathetic error messages across the UI.
Core Principles
| Principle | What it means |
|---|---|
| Clarity | Use simple, everyday language. Avoid jargon and vague descriptions. |
| Actionability | Tell the user exactly what to do next. If no action is needed, say so. |
| Empathy | Never blame the user. Use supportive, neutral phrasing. |
| Consistency | Use the same tone, structure, and terminology across all messages (e.g., don't mix "server error" and "system error" for the same issue). |
| Brevity | Keep it short — enough context to be useful, no more. |
| Accessibility | Follow WCAG guidelines so messages are understandable to users of all abilities. |
Anatomy of an Error Message
Every error message should answer up to three questions:
- What happened? State the problem plainly.
- Why did it happen? (optional) Add a brief reason if it helps the user understand.
- What should the user do next? Give a specific action or point to further help.
Structure:
| Component | Example |
|---|---|
| Header | "Unable to Process Request" |
| Description | "We encountered an issue while processing your request. Please try again." |
| Action/Help | "If the problem persists, contact support at support@document360.com." |
Writing Guidelines
| Guideline | ✅ Do | ❌ Don't |
|---|---|---|
| Use plain language | "The file size exceeds the allowed limit." | "File upload failed due to size constraints." |
| Be specific | "Invalid email address. Please enter a valid format (e.g., name@domain.com)." | "Input error." |
| Provide a solution | "The username is already taken. Try a different username." | "This username is not available." |
| Avoid technical jargon | "We couldn't connect to the server. Check your internet connection and try again." | "Server 503 error detected." |
| Use polite, positive language | "Something went wrong. Please try again in a few minutes." | "Error! Try again." |
| Align with context | "We couldn't save that. Please retry." | "Save error! Action blocked!" |
| Use active voice | "We couldn't find the requested article." | "The requested article was not found." |
| Avoid negative words | "We couldn't complete your request." | "Failed to process your request." |
Error codes: Include them only for complex or technical errors where they aid troubleshooting.
Example: "The request couldn't be processed (Error Code: 403). Contact support for assistance."
Common Error Scenarios
| Scenario | Error message |
|---|---|
| Invalid input | "Invalid password. Password must be at least 8 characters and include a number." |
| Missing required field | "Email address is required. Please enter your email to proceed." |
| Server timeout | "We're having trouble connecting to the server. Please try again later." |
| File upload error | "File upload failed. Ensure the file is under 5 MB and in a supported format." |
| Access denied | "You don't have permission to view this page. Contact your administrator." |
| Payment failure | "Payment couldn't be processed. Check your card details or try a different method." |
| Duplicate entry | "This category name already exists. Please choose a different name." |
| Session expired | "Your session has expired. Please log in again to continue." |
Pre-Publish Checklist
- Is the message clear and concise?
- Does it explain what went wrong?
- Does it offer an actionable next step?
- Is it free of technical jargon?
- Is the tone polite and professional?
- Is it consistent with other error messages in the product?
Maintenance
Review all error messages periodically as product features evolve, and update them promptly to prevent outdated or confusing guidance.