Error messages
An error message has one job: help the person understand what happened and what to do next. It’s not a place for technical codes, passive voice, or blame.
The structure
Every error message should answer three questions. Not all three need a separate sentence — for simple validation errors, one sentence covers all three. For system errors, all three deserve space.
Describe the problem in plain terms. Not an error code. Not a technical exception message. A plain English statement of what the system couldn’t do.
We couldn’t save your consultation. / This email address is already in use.
Include the reason if it helps the user understand their next step. Skip it if it adds length without adding clarity. “Your session expired” doesn’t need an explanation of why sessions expire.
Your file is 24 MB. The maximum size is 10 MB. / We lost the connection while saving.
Give a specific, actionable next step. “Try again” is acceptable for transient errors. For errors the user caused, be specific about what to fix. Always provide a path forward — even if it’s just a link to support.
Try again, or save as a PDF and re-upload. / Sign in again to continue.
Core principles
Never blame the user
“You entered an invalid email” is subtly blaming. “This doesn’t look like a valid email address” describes the problem without assigning fault. The distinction feels small, but it affects how someone feels about continuing — especially for community participants who might already feel uncertain about using the platform.
Never lead with error codes
Error codes belong in logs and support handoffs — not in user-facing messages. “Error 403” is meaningless to most users and alarming to many. If you need to include a code for support purposes, put it in a collapsed “details” section or generate a reference number the user can quote, not a raw HTTP code in the headline.
Be specific about what needs fixing
“Something went wrong — please try again” is the lowest-effort error message. It tells the user nothing. Was it their input? The network? The server? If the error is a transient system issue and you genuinely can’t be more specific, say so explicitly: “We’re having trouble connecting right now. Try again in a few seconds.”
Calm, not alarming
Error messages are not emergencies. Don’t use language like “Critical error”, “Fatal failure”, or all-caps emphasis. A calm, matter-of-fact tone helps the person assess the situation clearly rather than panic. Reserve stronger language for genuine data loss scenarios — and even then, be clear about what’s been saved.
Field-level validation errors
Inline validation errors appear next to or below the field that has a problem. They should be specific to the field and immediately actionable. Don’t repeat the field label — the proximity makes it clear what the error refers to.
Show validation errors after the user has attempted to leave the field or submit the form — not while they’re still typing.
Required field
Do
Consultation title is required
Or more conversationally: “Add a title to continue”
Don’t
This field cannot be empty
Generic and cold. Doesn’t name what’s missing.
Format error
Do
This doesn’t look like a valid email address
Or: “Check the email address and try again”
Don’t
You entered an invalid email
Blames the user for the error.
Value constraint
Do
Consultation title must be 100 characters or fewer (currently 112)
Don’t
Max length exceeded
Doesn’t say what the limit is or how far over it is.
Duplicate value
Do
This email address is already registered. Sign in instead, or use a different address.
Don’t
Email already exists
No path forward for the user.
File upload
Do
Your file is 14 MB. The maximum size is 10 MB. Try compressing the file or splitting it into smaller parts.
Don’t
File size exceeded the limit. Please upload a smaller file.
Doesn’t state the limit or how far over it is.
System errors
System errors are beyond the user’s control. The tone should make that clear — this isn’t something they did wrong. Be honest, offer a recovery path, and where relevant, reassure them their work is safe.
Save failure
Do
Couldn’t save your changes
We lost the connection while saving. Your last saved version is safe — try again when your connection is restored.
Try again
Don’t
Save failed
An error occurred. Please try again.
Page load failure
Do
Couldn’t load this consultation
There may be a temporary issue on our end. Refresh the page to try again — if it keeps happening, contact support.
Refresh page
Don’t
Error 500 — Internal Server Error
An unexpected error has occurred. Please contact your system administrator.
Action timeout
Do
That’s taking longer than expected
We’re still working on exporting your responses. You can wait, or come back later — we’ll notify you when it’s ready.
Don’t
Request timed out
The operation failed. Please try again.
Permission errors
Permission errors need careful handling. The user needs to understand why they can’t do something — without feeling like they’ve been blocked arbitrarily or reprimanded for trying.
Be clear about what the limitation is and who to contact to resolve it. Don’t leave someone wondering whether they should keep trying.
Insufficient permissions
Do
You don’t have permission to delete consultations
Only project administrators can delete consultations. Ask your admin to do this, or to give you administrator access.
Don’t
Access denied
You are not permitted to perform this action.
Account suspended or restricted
Do
Your account access has been restricted
Contact your organisation administrator to find out what’s happened and how to restore access.
Don’t
Account disabled
Your account has been disabled. Contact support.
No explanation, no human tone, no path forward.
Session expired
Do
Your session has expired
Sign in again to continue where you left off.
Sign in
Don’t
Error: Authentication token invalid
You must re-authenticate to proceed.
Was this page helpful?