Anatomy of an error
Every error message answers two questions, in this order:
- What happened? One factual sentence.
- What can the reader do next? One concrete action.
If you can add a third sentence with helpful context (an error code, a docs link, a suspected cause), do, but only if it's actionable.
Tone in errors
Errors are factual and actionable. They are not apologetic, not cheerful, and never sarcastic. The reader is already frustrated; their time is the thing you're spending.
|
✅ Prefer |
❌ Avoid |
|---|---|
|
Could not save the dashboard. Try again. |
Oops! Something went wrong. |
|
AppSignal could not verify the key. |
Sorry, we couldn't do that right now :( |
|
Response time above 400 ms for the last 5 minutes. |
Uh oh — your dashboard crashed! |
Don't blame the reader
When the system rejected an input, describe what's wrong with the input — not what the reader "did". "Invalid value" is fine; "you entered an invalid value" is needlessly accusatory.
|
✅ Prefer |
❌ Avoid |
|---|---|
|
AppSignal could not process the request. |
You failed to complete the setup. |
|
The email format is not recognized. |
You entered an invalid email. |