Writing Effective Error Messages in English: Principles and Examples
How to write clear, actionable English error messages for software — with good vs bad examples, vocabulary of error states, and rewrite exercises.
Error messages are the most-read writing in most applications, and the most neglected. Users encounter them at moments of frustration or confusion — the worst possible time for vague, technical, or accusatory language. Writing clear, human error messages is a skill that sits at the intersection of technical writing, UX, and English communication. This guide covers the core principles and gives you concrete before/after rewrites.
The Five Principles of Good Error Messages
1. Be Specific
A good error message tells the user exactly what went wrong. A vague message forces the user to guess.
| Bad | Good |
|---|---|
| ”An error occurred." | "Your session expired. Please sign in again." |
| "Something went wrong." | "We couldn’t save your changes — the server returned a timeout." |
| "Invalid input." | "Your password must be at least 8 characters and include one number.” |
Specificity is not about technical detail — it is about communicating the relevant fact clearly.
2. Be Actionable
Every error message should answer the implicit question: “What do I do now?” If the user reads the message and does not know their next step, the message has failed.
- No clear action: “Request failed.”
- Actionable: “We couldn’t process your request. Please check your internet connection and try again.”
Sometimes the action is “contact support” or “try again later.” That is fine — just say it explicitly.
3. Don’t Blame the User
Blame language is both inaccurate and alienating. Most errors are caused by system limitations, design gaps, or edge cases the developer did not anticipate.
| Blaming | Neutral |
|---|---|
| ”You entered an invalid date." | "Please enter a date in the format DD/MM/YYYY." |
| "You must agree to the terms." | "To continue, please accept the Terms of Service." |
| "You’ve exceeded the limit." | "You’ve reached the maximum of 5 projects on the free plan. Upgrade to add more.” |
Note that the neutral versions are also more specific and actionable — good error messages naturally combine all five principles.
4. Include Recovery Steps
Where possible, tell the user exactly how to fix the problem — not just what the problem is.
- “Your credit card was declined. Please check the card number, expiry date, and billing address, then try again.”
- “This email address is already registered. Sign in instead, or reset your password if you’ve forgotten it.”
- “The file you uploaded is 15 MB. Please reduce it to under 10 MB before uploading.”
Recovery steps convert a dead end into a path forward.
5. Avoid Technical Jargon
Unless the audience is explicitly technical (a developer console, a CLI tool), avoid exposing internal technical language.
| Jargon | Plain English |
|---|---|
| ”HTTP 500 Internal Server Error" | "Something went wrong on our end. Please try again in a moment." |
| "ECONNREFUSED: Connection refused to 127.0.0.1:5432" | "We can’t reach our database right now. Please try again later." |
| "Null reference exception in UserService" | "We couldn’t load your profile. Please refresh the page.” |
Vocabulary of Error States
Different types of errors have different standard English descriptions. Using consistent, recognised vocabulary helps users and developers alike.
| Error State | Technical Code | User-Facing Language |
|---|---|---|
| Not found | 404 | ”We couldn’t find that page.” / “This resource no longer exists.” |
| Unauthorised | 401 | ”Please sign in to continue.” |
| Forbidden | 403 | ”You don’t have permission to access this.” |
| Timeout | 408 / 504 | ”The request took too long. Please try again.” |
| Server error | 500 | ”Something went wrong on our end. We’re looking into it.” |
| Validation error | 422 | ”Please check the highlighted fields and try again.” |
| Rate limited | 429 | ”You’ve made too many requests. Please wait a moment before trying again.” |
| Conflict | 409 | ”This record was modified by someone else. Please refresh and try again.” |
| Gone | 410 | ”This content has been permanently removed.” |
Error Message Rewrites
Here are five real-world bad error messages rewritten using the principles above.
Rewrite 1: Generic server error
Original:
Error 500. Try again later.
Rewritten:
Something went wrong on our end. We’ve been notified and are looking into it. Please try again in a few minutes.
Changes: Named the error in plain language, reassured the user the team is aware, gave a time expectation.
Rewrite 2: File upload failure
Original:
File rejected.
Rewritten:
We couldn’t upload your file. Only JPG, PNG, and PDF files are supported, and the maximum file size is 10 MB. Please check your file and try again.
Changes: Specified the rejection reason, listed valid options, provided recovery action.
Rewrite 3: Login failure
Original:
Invalid credentials. Authentication failed.
Rewritten:
The email or password you entered doesn’t match our records. Please try again, or reset your password if you’ve forgotten it.
Changes: Removed jargon (“credentials”, “authentication”), softened the framing, offered a recovery path.
Rewrite 4: Form validation
Original:
You entered invalid data in field 3.
Rewritten:
Please enter a valid phone number. We accept UK numbers in the format 07XXX XXXXXX or +44 7XXX XXXXXX.
Changes: Named the field in a user-facing way, gave a precise format example.
Rewrite 5: Permission error
Original:
Access denied. You lack the required permissions.
Rewritten:
You don’t have permission to view this page. If you think this is a mistake, contact your account administrator.
Changes: Removed “lack” (slightly blaming), added a recovery path for edge cases.
Writing Error Messages for Different Audiences
The principles above apply broadly, but register varies by context:
- Consumer app (non-technical users): Plain English, friendly tone, minimal jargon, always include recovery steps.
- Developer API / CLI tool: More technical detail is appropriate; include error codes, relevant field names, HTTP methods. Developers want precision.
- Admin dashboard: A middle ground — be specific about what failed, include technical identifiers, but avoid raw stack traces.
Key Takeaways
- Specific, actionable, non-blaming error messages reduce user frustration and support tickets.
- Always answer the question: “What should I do now?”
- Use plain English for consumer-facing messages; reserve technical language for developer-facing contexts.
- Consistency in vocabulary (use the same language for the same error state throughout an app) reduces confusion.
- Error messages are an opportunity to communicate competence and care — use it.