Writing for errors

Error messages should help users understand what went wrong and how to fix it - not confuse, blame, or frustrate them.

We follow the NN/G error message guideline for writing great error messages.

Guidelines

What to do

• ✅ Always show a message when something goes wrong.
  The worst error is one that goes unnoticed. Never leave users guessing.

• ✅ Use plain, human-readable language.
  Avoid vague codes like “An error of type 2 has occurred.”

• ✅ Be polite — never blame the user.
  Avoid phrases like “Illegal command” that imply the user did something wrong.

• ✅ Be specific.
  Describe the exact issue. “Invalid email format” is better than “Syntax error.”

• ✅ Offer next steps.
  Help users fix the problem. Instead of “Out of stock,” try:
  “This product is currently unavailable. Want to be notified when it's back?”

• ✅ Make it visible.
  The message should stand out and clearly show where the issue occurred.

Form validation

Best practices

• Show errors inline (below the field), not just at the top of the form.
• Clearly indicate the field in error (e.g. use the field invalid state if available).
• Avoid generic errors like “Invalid input.”
• Avoid technical jargon (e.g. regex, constraints).
• Say what’s wrong and how to fix it.

Examples

❌ Bad Message	✅ Good Message
Invalid input.	Enter a valid email address.
Required field.	First name is required.
Password too weak.	Use at least 8 characters, including a number.
Value exceeds limit.	Max file size is 5MB. Try uploading a smaller file.

System messages

Best practices

• Make messages calm, clear, and non-disruptive where possible.
• Acknowledge what happened, even if the user isn’t at fault.
• Suggest retrying or give a clear next action.

Examples

❌ Bad Message	✅ Good Message
Something went wrong.	We couldn’t complete your request. Please try again.
Unexpected error.	The page didn’t load as expected. Try refreshing the browser.
Error 500	We’re having trouble on our end. Try again in a few minutes.
Access denied.	You don’t have permission to view this. Contact your admin if needed.
Action failed.	We couldn’t save your changes. Please check your connection.

Technical error states

These messages are often seen by support teams, developers, or power users. Use technical detail when useful, but pair it with plain language.

Best practices

• Explain what happened in plain language.
• Include technical codes or logs only if they help with troubleshooting.
• If recoverable, tell users what to do next.
• If not, provide a link or contact for help.

Examples

❌ Bad Message	✅ Good Message
Error 503. Service unavailable.	The system is temporarily unavailable. Try again shortly. (Error 503)
Timeout.	The request took too long to complete. Please try again.
Failed to authenticate user.	We couldn’t log you in. Check your credentials and try again.
Connection refused.	We couldn’t connect to the server. Check your internet connection.
An error of type 2 has occurred.	Something went wrong while loading data. Try again or contact support (Error 2).