# Error-messages



# Error Message Guidelines

Clear, empathetic, and actionable error messages help users recover quickly, reduce frustration, and build trust. Use these principles and examples to craft messages that guide users effectively.

---

## 1. Be Clear and Concise

- Use plain, everyday language.
- Avoid error codes, system terminology, and technical jargon.
- Be short but specific—no more than one or two short sentences.

**Good**: *We couldn’t find this page.*  
**Poor**: *Error 404: Page not found.*

---

## 2. Be Explicit About What Went Wrong

- Clearly state the exact issue—don’t be vague.
- Include necessary context without overwhelming the user.

**Good**: *Please enter a valid phone number.*  
**Poor**: *Submission failed.*

---

## 3. Offer a Solution

- Guide users on what to do next.
- Be specific about the required fix or input.

**Good**: *Check your username and try again.*  
**Poor**: *Invalid input.*

---

## 4. Be Empathetic and Encouraging

- Write in a tone that feels helpful and human—not cold or blaming.
- Assume the user had good intentions.

**Good**: *Having trouble signing in? Let’s reset your password.*  
**Poor**: *Login failed.*

---

## 5. Use Positive Framing

- Avoid phrasing that blames the user.
- Focus on the action that will lead to success.

**Good**: *Fill out all required fields to continue.*  
**Poor**: *You missed required fields.*

---

## 6. Place Messages in the Right Context

- Show the error next to or inside the field it relates to.
- Avoid generic banners or popups unless the error applies globally.

---

## 7. Prevent Errors Through Instruction

- Use inline helper text to reduce user errors.
- Validate inputs in real time where possible.

**Good**: *Password must include at least one number and a special character.*

---

## 8. Be Conversational

- Sound like a real person speaking to another person.
- Use a friendly, familiar tone aligned with your brand voice.

**Good**: *We need your email to keep you updated.*  
**Poor**: *Field is mandatory.*

---

## 9. Test and Improve Regularly

- Run usability testing on key forms and flows.
- A/B test message variants to find the most effective versions.
- Monitor analytics and support tickets to spot confusing errors.

---

## 10. Avoid Triggers and Negative Emotion

- Don’t embarrass or alarm the user.
- Be cautious with humor—it must fit the context and brand.
- Keep the tone calm, even when something goes wrong.

**Good**: *Oops, something went wrong. Let’s try again.*

---

## 11. Design for Accessibility

- Use sufficient color contrast for error messages.
  - Follow the WCAG minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text. This helps users with low vision or color vision deficiency.
- Don’t rely on color alone—use icons, labels, and ARIA roles.
  - For example, instead of only using red text to indicate an error, combine it with a clear error message, an icon (like ❌), and accessible labels. This ensures that colorblind users or those using screen readers understand the issue.
- Write error messages that are screen-reader friendly.
  - The message is real text (not an image of text).
  - The error message is programmatically associated with the relevant field using aria-describedby, aria-invalid, or aria-live.
  - The message is concise, polite, and clearly indicates how to fix the issue.

---

## 12. Stay Consistent

- Use standardized language for recurring patterns.
- Match tone and terminology across buttons, labels, and messages.

---

## Reusable Patterns and Examples

### Login  
*Incorrect username or password. Need help signing in?*

### Job Posting  
*This position already exists. Review your entry and try again.*

### Candidate Submission  
*Unable to submit candidate profile. Check the required fields and resubmit.*

### Search  
*We couldn't find any matches. Adjust your filters and try again.*