Everyday Guidebooks
Cover of The Copywriting Guide to Helpful Error Messages

More Books

The Copywriting Guide to Helpful Error Messages

How to Explain Problems, Show Their Impact, and Help Users Take the Next Step

by Todd Michael

Available now

When something goes wrong on a website or app, a few words can determine whether a user recovers or gives up. This copywriting guide shows you how to replace vague, blaming, and unhelpful errors with messages people can act on.

Learn a repeatable method for identifying the problem, explaining what it means for the user, and offering a practical next step. Work through before-and-after examples for forms, payments, permissions, and failures whose cause is uncertain. You'll also learn how to ask better questions when the technical details are missing, avoid promises your product cannot keep, and review messages for clarity and accessibility.

With exercises, checklists, and adaptable patterns, this reference is useful whether you're writing your first interface or improving an established product. You don't need to be a developer—just be ready to look closely at what users need when a task doesn't go as planned.

Contents
  1. 1. What an Error Message Is For
  2. 2. Find Out What Went Wrong
  3. 3. Explain the Effect
  4. Start with the interrupted task
  5. Distinguish the action from the result
  6. Be precise about saved work
  7. Say what was—and was not—submitted
  8. Account for partial progress
  9. Name the consequence, not the machinery
  10. Treat uncertainty as a state, not a flaw
  11. Use the surrounding interface as evidence
  12. A side-by-side review
  13. Practice: write the effect before the instruction
  14. 4. Offer a Practical Next Step
  15. 5. Build a Clear Message
  16. Start with the user’s immediate question
  17. Choose an order that fits the situation
  18. Give headings a job
  19. Make supporting text earn its place
  20. Use plain language without removing meaning
  21. Remove detail that does not help recovery
  22. Respect the user without assigning blame
  23. Make the action match the control
  24. Edit a message from evidence to final copy
  25. Practice: assemble, then subtract
  26. 6. Forms and Validation
  27. 7. Payments and Transactions
  28. 8. Permissions and Access
  29. 9. When the Cause Is Uncertain
  30. 10. Match the Message to the Moment
  31. One recovery, several surfaces
  32. Inline errors: close to the correction
  33. Banners: context without taking over
  34. Dialogs: reserve the interruption for a decision
  35. Full-page failures: restore orientation
  36. Timing and repetition
  37. Review the surrounding interface
  38. Exercise: follow the interruption
  39. 11. Write for Access and Understanding
  40. 12. Work with Product and Technical Teams

Read a sample: 1. What an Error Message Is For

A person has filled out a form, checked the details, and pressed Submit. Instead of the confirmation they expected, a message appears:

> Something went wrong.

The message reports an interruption, but it leaves the person with work to do. Did the form go through? Are their entries still there? Should they submit again, start over, or contact someone?

An error message is part of the product’s response to a problem. Its purpose is not simply to announce that a system detected an error. It should help a person understand what happened to the task they were trying to complete and what they can usefully do next.

That does not mean every message needs a long explanation. A missing field may need only a short instruction beside the field. An uncertain payment may need more context because the consequences of repeating the action are different. The right amount of copy depends on what the user needs to know, not on how much the system knows.

This chapter introduces a way to examine error messages through three questions:

- Problem: What went wrong, as far as the product can reliably tell? - Effect: What happened to the user’s action, information, or progress? - Next step: What can the user do now?

These are not three mandatory sentences or a rigid template. They are three kinds of information to look for when a task is interrupted. Sometimes one sentence can provide all the information a person needs. Sometimes the answer to one of the questions is not yet known, and the honest message must say so.

People rarely arrive at an error message because they want to inspect software. They are trying to do something: create an account, send a report, pay an invoice, upload a file, or change a setting.

That task gives the message its meaning. Consider:

> Error 403.

A developer may recognize the number as a useful diagnostic detail. A person trying to open a shared report may not know whether the report is missing, whether their account is broken, or whether they need someone’s permission.

A more useful message might be:

> You can’t open this report > Ask the report owner to give you access.

The revision connects the problem to the person’s goal and offers a route forward. It does not explain why access was denied, because the message has not established that reason. Perhaps the report has not been shared with this person; perhaps a broader restriction applies. The copy should not select a cause merely because it sounds plausible.

Even this improved version depends on the product’s behavior. The team needs to know that contacting the report owner is a realistic option. If only an administrator can grant access, the instruction should name that route instead. Good error copy is grounded in the actual recovery path, not in a generic idea of what users usually do.

When reviewing a message, begin one step before it appears. What action did the person take? What result did they expect? What can they see now? Those questions shift the review from “Is this sentence friendly?” to “Does this response help someone continue?”

A system notification tells someone that an event occurred. An error message may need to do that, but a useful one goes further.

Compare these examples:

> Upload failed.

> The file couldn’t be uploaded > Choose a file smaller than 10 MB and try again.

The first message names the failed action. It does not say what the person can change. The second supplies a recovery step—but only works if the product has confirmed that the file exceeds a 10 MB limit. If an upload can also fail because the connection was interrupted, showing the same instruction for every failure would send some users in the wrong direction.

Now consider a different, uncertain failure:

> The file couldn’t be uploaded > Check your connection, then try uploading the file again.

This gives the user a possible action without claiming that the connection caused the problem. It is appropriate only if trying the upload again is a supported, sensible step in that situation. If the product might have received the file despite not showing confirmation, the team needs to establish what a repeat upload would do before recommending it.

The distinction matters because confident instructions can be as misleading as confident explanations. “Choose a smaller file” implies that size is the obstacle. “Try again” implies that repeating the action is a reasonable way to recover. Both are product claims, even when they look like ordinary copy.

A message supports recovery when it helps the user make a better decision than they could make without it. That decision might be to correct a field, wait for a confirmed process to finish, check the status of an action, or ask someone with the right permissions for help. It might also be to stop and contact support rather than repeat an action whose outcome is unclear.

The problem, effect, and next step are related, but they are not interchangeable. Separating them helps you see what a draft says—and what it leaves for the user to infer.

The problem is the condition or failure the product can identify.

In a form, the problem might be that a required email address is missing. During a file upload, it might be that the selected file exceeds a known size limit.…

More More Books

Cover of Dog Breeds for Real LifeDog Breeds for Real LifeAvailable nowCover of How to Find the Right Dog Breed for Your HouseholdHow to Find the Right Dog Breed for Your HouseholdAvailable nowCover of Digital Nomad Ideas for Accessible Remote WorkDigital Nomad Ideas for Accessible Remote WorkAvailable nowCover of The Bathhouse Keeper's Day OffThe Bathhouse Keeper's Day OffAvailable nowCover of A Hurricane Guide for CaregiversA Hurricane Guide for CaregiversAvailable nowThe Fountain Pen FamiliarComing soon

About Todd Michael

Todd Michael is an American author and the founder of ToddMichael.tv. He writes practical, plain-English books on money, health, preparedness, technology, games, humor and more.

About the author Todd Michael · Todd Michael’s author site

Part of the ToddMichael.tv network.