error-ux

Error UX Skill

Purpose

Provides principles and patterns for writing error messages that help users recover instead of leaving them stuck.

The Error Message Framework

Every error message should answer three questions:

1. What Happened (Symptom)

State the problem in user terms, not system terms.

System Speak	User Speak
ETIMEDOUT	The request took too long
ECONNREFUSED	Cannot connect to the service
403 Forbidden	You don't have permission
ENOMEM	The system is overloaded
Deadlock detected	Please try again in a moment
ENOENT	File or resource not found
EPERM	Permission denied
EEXIST	Already exists

2. Why It Happened (Cause)

Give the most likely explanation without requiring technical knowledge.

Common causes to surface:

• Network connectivity issues
• Invalid input (be specific about which field)
• Missing permissions
• Resource not found (was it deleted?)
• Rate limiting
• Service temporarily unavailable
• Session expired
• Configuration missing

3. What To Do (Resolution)

Provide concrete next steps. Prioritize:

1. Self-service fixes ("Check your internet connection")
2. Retry suggestions ("Try again in a few minutes")
3. Alternative paths ("Use X instead")
4. Support escalation (last resort, with context to provide)

Error Categories and Patterns

Input Validation Errors

Always specify:

• Which field failed
• What was wrong with it
• What format is expected

Bad:  "Validation error"
Good: "Phone number must be 10 digits. You entered: 555-123 (7 digits)"

Bad:  "Invalid input"
Good: "Email address is invalid: 'not-an-email' is missing the @ symbol"

Bad:  "Field required"
Good: "Please enter your last name"

Authentication/Authorization Errors

Be vague enough for security, helpful enough for legitimate users:

Bad:  "Invalid password for user [email protected]"  // Confirms email exists
Good: "Email or password is incorrect. [Forgot password?]"

Bad:  "You don't have admin role"  // Leaks role information
Good: "You don't have permission to access this page. Contact your administrator if you need access."

Bad:  "Token expired at 2024-01-15T10:30:00"  // Leaks timing info
Good: "Your session has expired. Please log in again."