templates/error-message-template.md

Error Message Template

Use this template to write clear, actionable error messages that help users recover.

Structure

[What failed] [Why it might have failed, if known] [What to do next]

Template

Inline Error (Form Validation)

Format: Brief, immediate correction guidance

[Field requirement or constraint]

Examples:

• Email must include @
• Password needs 8+ characters
• Card number is incomplete
• Choose a future date

Detour Error (Recoverable Problem)

Format: Problem + Solution

**Title**: [Action that failed]
**Body**: [Brief explanation]. [Recovery instruction].
**Button**: [Specific recovery action]

Example:

**Title**: Can't save changes
**Body**: Check your internet connection and try again.
**Button**: Retry

Blocking Error (System Issue)

Format: Clear explanation + Timeline + Reassurance

**Title**: [What's unavailable]
**Body**: [Why it's unavailable]. [When it will be available]. [Reassurance about user data].
**Button**: [Status check or alternative action]

Example:

**Title**: Service temporarily unavailable  
**Body**: We're updating our systems and will be back in about 15 minutes. Your data is safe.
**Button**: Check status

Error Message Checklist

Before finalizing an error message, verify:

• Avoids blame — No "invalid," "illegal," "wrong," "error"
• Empathetic tone — Acknowledge user frustration
• Specific problem — Not generic "something went wrong"
• Clear recovery — Tell user exactly what to do
• Front-loaded — Most important info first
• Active voice — "We couldn't save" not "changes could not be saved"
• Human language — Not system codes or technical jargon

Voice Variations by Context

High-Stakes Error (Payment, Security, Data Loss)

Tone: Serious, clear, reassuring

We couldn't process your payment. Your card wasn't charged. Check your card details and try again.

Low-Stakes Error (Optional Feature, Nice-to-Have)

Tone: Light, helpful, not dramatic

Couldn't load preview. Refresh to try again.

First-Time User Error

Tone: Educational, patient

Profile photo must be under 5MB. Try a smaller file or compress your image.

Common Mistakes to Avoid

❌ Vague: "An error occurred" ✅ Specific: "We couldn't save your changes"

❌ Blaming: "Invalid email address" ✅ Guiding: "Email must include @"

❌ Technical: "ERR_CONNECTION_TIMEOUT" ✅ Human: "Connection timed out. Check your internet and try again."

❌ No solution: "Upload failed" ✅ Actionable: "Upload failed. Check your file size and try again."

❌ Passive: "Your request could not be processed" ✅ Active: "We couldn't process your request"

Quick Fill Template

Use this for rapid error message drafting:

What failed: Why (if known): What user should do:

Draft: [What failed]. [Why, if known]. [Next action].

Example filled:

• What failed: Couldn't send invite
• Why: Email bounced
• What to do: Check spelling

Draft: "Couldn't send invite. Check the email address and try again."