On this page
Error messages
How to write error messages that say what happened and what to do next.
Error messages are some of the most important content in a product. When something goes wrong, the user needs to understand what happened and what to do next. A poor error message leaves them stuck.
The best error message is the one that never appears. Before writing an error message, consider whether the error can be prevented through design: better input constraints, auto-correction, or clearer hints. Only surface an error message when other options are exhausted.
Structure
Every error message must answer: what happened + why (if useful) + what to do next.
Do
Date of birth doesn't match. Ask the customer to confirm, then re-enter.
Don't
Invalid input.
Oops! Something went wrong.
Include the underlying cause only when it genuinely helps the user resolve the issue. Do not explain system constraints for their own sake.
Language
Avoid the word "invalid". It is jargon that tells the user nothing. Describe what is wrong and what a valid input looks like.
Do
Sort code must be 6 digits, for example 12-34-56.
Don't
Invalid sort code.
For errors affecting the user's current task, lead with the effect, not the technical cause.
Do
Couldn't save payment plan
Don't
HTTP 500 error
For multiple errors, tell the user exactly how many changes are needed and what they are.
Do
To save, make 2 changes: Enter a valid MPAN. Add a primary contact.
Don't
There are 2 errors on this page.
For errors without a resolution, give a concrete action rather than a vague link.
Do
Something went wrong. Refresh the page to try again.
Don't
Something went wrong. Learn more.
Use the user's own data where possible. Specific values reduce the need to cross-reference.
Do
Payment of £247.50 on 14 Jan 2025 couldn't be processed. Check the account details and try again.
Don't
Payment couldn't be processed.
Two types of error
System errors
The platform or a third party failed. Use neutral, impersonal phrasing. Do not imply the user did something wrong.
Do
Couldn't load this account. Check your connection or try again.
Don't
Account failed to load.
User errors
The user entered something incorrectly. Use passive voice or neutral framing to avoid sounding accusatory. Describe the problem and what a valid input looks like.
Do
Sort code must be 6 digits. For example, 12-34-56.
The payment has been declined. Check the card details and try again.
Don't
You entered the wrong sort code.
Tone by severity
Match the tone to the consequence of the error.
| Tone | When to use | Example |
|---|---|---|
| Instructive | Low-consequence, simple fix | Unable to load this page. |
| Reassuring | Minor error where the user may be worried | Servers timed out. Try again, and if the problem persists, contact support. |
| Supportive | Serious error, data loss, or major action required | Something went wrong. Your progress has been saved. Contact support if this continues. |
Apologies
Do not apologise for minor errors. Overuse makes apologies meaningless and delays the useful information. Reserve sorry for serious errors that involve data loss or require significant user action to resolve.
Never use whimsical language: oops, whoops, oh no. These undermine trust and are inappropriate in operational contexts.
Error codes
Include error codes only if the user can use them to contact support or resolve the issue. Always place the code at the end of the message.
Do
This profile is unavailable. Try reloading. (Error code: 10213)
Don't
Error 10213. This profile is unavailable.
Validation errors on forms
Always validate on form submission. Never validate as the user types, it interrupts users who are mid-entry.
When errors appear after submission:
- Show them adjacent to the relevant field, below the label and hint text
- List them in the ErrorSummaryNotification at the top of the form, with a link to each field
- Use the same wording in the summary as in the inline error, if the inline error contains a link, omit the link from the summary version
The ErrorSummaryNotification title should remain as There is a problem. Consistent wording helps users recognise the error pattern across the platform.
Two approaches to validation error wording
Instruction, tell the user directly what to do. For example: Enter your first name
Use when the fix is obvious and the field purpose is clear.
Description, describe what is wrong, then what to do. For example: First name must be 35 characters or fewer
Use when you need to explain a constraint the user may not have anticipated.
Choose whichever sounds more natural and helpful. Do not mix both approaches in the same message.
Do and don't
| Don't | Do |
|---|---|
| An error occurred | Your meter read could not be submitted |
| Invalid | Mobile number must be 11 digits |
| You forgot to enter your name | Enter your last name |
| Sorry, something went wrong! | Supply point data unavailable |
| Whoops, please try again | Refresh to try again. If this error persists, contact your team lead. |
| No access to this page, sorry! | You don't have permission to view managed exceptions |
| Please enter a valid email address | Enter a valid email address |
| Error 10213. Profile unavailable. | This profile is unavailable. (Error code: 10213) |