Error messages
An error is a contract: tell the reader what happened, and what to do next. If you can't write the second part, the error isn't ready.
Anatomy
Every error answers two questions, in this order:
- What happened? One factual sentence.
- What can the reader do next? One concrete action.
A third sentence — an error code, a docs link, a suspected cause — earns its place only if it is actionable.
Tone
Errors are factual and actionable. Not apologetic, not cheerful, never sarcastic. The reader is already frustrated; their time is what you are 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 rejects an input, describe what is 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. |
Don't rely on colour
A red border alone does not communicate an error. Pair it with an icon and a sentence. See accessibility.