An error message appears when someone tries to complete a task and something gets in the way. If it only announces that there was a problem, the person is left unsure whether to correct a detail, wait, try again, or ask for help. For product and technology teams, the goal is not to dress up a failure: it is to help people decide what to do next and prevent them from losing their work or repeating an action with consequences.
Designing useful messages requires understanding what caused the error, what information is still available, and which recovery options exist. It also means coordinating the wording with the application’s actual behavior. An instruction such as “Try again” is harmful if the operation has already completed or repeating it could create a duplicate.
Classify the error before writing the message
Start by identifying what is preventing the task from being completed and who can resolve it. This classification helps you choose both the content and the action to offer:
- An error the person can fix: a required field is missing, a value has an invalid format, or a selection does not meet a requirement. Explain what to check and point to the specific field.
- A temporary system problem: the application cannot complete an operation because of an incident or a temporary condition. Say whether it makes sense to wait or try again, and explain what will happen to the data.
- An external dependency: a connected service is not responding or has rejected the request. Do not blame the user or promise when the issue will be resolved. Communicate what the application knows and offer a workable alternative.
- A situation that requires assistance: the person cannot resolve the blocker in the interface, or the case needs to be checked. Explain how to contact support and what useful information to provide.
You do not need to expose the technical architecture to make these distinctions. You do need to agree with the development team on the operation’s status, whether changes were saved, and whether it is safe to repeat the action. Without that information, the content team cannot provide reliable instructions.
Explain the cause, impact, and next step
A practical message answers three questions in everyday language: what happened, what it means, and what the person can do now. If it is relevant, also say whether the data was saved. There is no need to explain every internal detail; provide enough context for the person to act.
For example, “We couldn’t save the form because the phone number is missing. Add a number in the Phone field and save again” describes the outcome, the reason, and the fix. By contrast, “Error processing request” does not say what to do. For a temporary problem, wording such as “We couldn’t load your results. Your filters are still available; try again” is helpful only if the interface really does preserve those filters.
Check every message against the product’s actual state. If you cannot confirm that the data was saved, do not say it is safe. If you do not know the cause, do not invent one: explain the outcome and offer a safe action. A limited but accurate explanation is better than a reassuring promise the application cannot keep.
Choose a recovery action that will not make things worse
The suggested action should match the type of failure and the consequences of repeating the operation. Before displaying a button or instruction, answer these questions:
- Can the person fix it? If so, direct their attention to the field or choice that needs changing, and preserve everything else where possible.
- Is it safe to try again? If the operation may have completed even though the interface did not confirm it, do not offer a blind retry. Check the status or explain how to verify it.
- Can they continue another way? If a functional alternative exists, such as saving a draft or completing the process later, make it visible without hiding the primary option.
- Is support needed? Provide an available contact channel and, if useful, a reference number. Do not make contacting support the only way forward when the person can resolve the problem themselves.
For sensitive operations—such as placing an order, making a payment, or publishing content—agree with the development team on how the result is confirmed and how repeated actions are prevented. The message shown to the user must reflect that behavior; wording alone cannot guarantee that an operation is safe.
Write clearly and without blame
Write for the person trying to complete a task, not for someone debugging the system. Avoid internal codes, component names, and phrases such as “invalid request” if they do not explain what to fix. A code may help support staff, but it should accompany a clear explanation, not replace one.
Use a direct, neutral voice. “We couldn’t verify the address” describes the outcome without accusing anyone. “You entered the address incorrectly” blames the person and may be wrong: perhaps the expected format was unclear. Also avoid vague instructions such as “Check your details” when you can identify which detail needs attention.
Being brief is useful, but not if it means leaving out an important consequence. Say if an answer was deleted, if the process is still pending, or if the person can try again without creating a duplicate. If you do not know which situation applies, pause the writing and ask the technical team to define the state.
Make the message noticeable and usable
The text should appear near the affected element or somewhere that makes sense for the scope of the problem. A field error is usually more useful next to the field than in a distant alert. If the whole task is blocked, a general message can explain the situation and offer a primary action. Do not rely on color alone to communicate that something went wrong; pair it with identifiable text.
Check that people can understand the message using a keyboard and assistive technologies, and that they can find the related field without having to guess. In forms, check whether the error remains visible after the person corrects the value, and whether focus and navigation make it possible to continue. Accessibility is not achieved by writing a good sentence if the notice never reaches the person who needs it.
Timing matters too: an alert that disappears before it can be read, or appears before someone has finished typing, can add to the confusion. Validate the behavior in the real interface and across relevant states, not just the wording in a document.
Document and validate an error matrix
To avoid different responses to the same failure, create a shared matrix for product, design, development, and customer support. Include at least:
- The name of the state and the known source of the problem.
- The task the person was performing and the scope of the impact.
- Which data was saved, discarded, or is still awaiting confirmation.
- The visible text, its location, and the available action.
- Who is responsible for confirming the behavior and when to escalate to support.
Prioritize errors that block important tasks, can cause data loss, or lead to repeated support requests. Test messages with real tasks: observe whether people understand what happened, find the next step, and continue without outside instructions. Record where they abandon the task or try again, along with the questions received by support, and compare those signals before and after changes. A drop in support requests alone does not prove that the problem has been solved: it may mean people have stopped trying to complete the task.
Review the matrix whenever a flow, dependency, or saving logic changes. The quality of a message is not measured by how friendly it sounds, but by whether it describes the state accurately and helps people act. When the product does not yet know the outcome, the best choice may be to avoid an automatic retry, explain the uncertainty, and offer a safe way to check the status or get assistance.