Edit AI Error Messages Around the Actual Failure and Next Step
Turn AI-drafted errors into useful guidance by checking the failure state, saved input, available controls, and safe next action before polishing the wording.
Before approving “Something went wrong. Your work is safe. Try again,” ask what the product actually knows. That short message asserts a failure, preserved work, and a suitable recovery action. An AI can write all three claims without evidence for any of them.
Start an error-message edit with the system state. Establish the outcome, the condition of the user's input, and the action they can take. Then express those facts plainly. When completion is uncertain, the message must keep that uncertainty visible.
Give the editor a state brief
A screenshot or isolated error code rarely tells the whole story. Ask the product or process owner for the facts behind each message before asking a writing tool for alternatives.
| Brief field | Facts to establish |
|---|---|
| Trigger | The condition that displays this particular message |
| Outcome | Whether the operation was rejected, completed, or remains unconfirmed |
| Input | What the interface retains and what the service actually saves |
| Next action | A correction, control, or help route available to this user |
| Unknowns | Causes, recovery times, and promises that have not been established |
Text still visible in a form is not necessarily saved to an account. A rejected upload is also different from an upload that may have succeeded before its response disappeared. Avoid making these states sound interchangeable.
Microsoft's error-message guidelines recommend specificity about known causes and language appropriate to the audience. Specificity must follow evidence. Use the fact-checking workflow to record operational claims still awaiting an owner's confirmation.
Match the instruction to the type of problem
A field needs correction
Identify the field and its actual requirement. “Invalid file” gives little help. A message naming permitted formats can help, provided those formats have been verified. Do not add a size limit or example because it seems plausible.
The GOV.UK error-message component distinguishes input errors from problems with the service and recommends specific, consistent messages. Its instruction to retain entered answers concerns implementation. Writing “your answers are preserved” cannot make a product preserve them.
The service is unavailable
Explain which task cannot be completed and which useful route remains. A service outage should not send somebody back to correct valid input. The GOV.UK service-problem pattern includes information about entered answers and relevant contact options. Obtain those facts for your service; do not borrow promises from a sample page.
Completion cannot be confirmed
An unknown outcome needs a way to check what happened before repeating the action. Calling it a failure could cause duplicate uploads, orders, or submissions. Ask the owner to establish a safe checking route. If none exists, resolve that product question before approving a retry instruction.
Four upload messages, checked against one fictional brief
This is an invented teaching example, not a description of RewriteMax, a customer story, or a usability study.
The owner of an imaginary community archive confirms these facts:
- The Document field accepts PDFs up to and including 8 MB.
- Rejected files are not uploaded. Other answers remain in the form while the user stays on the page, but the service does not save a draft.
- Choose file selects a replacement.
- A lost upload response leaves completion unknown. View uploads shows every completed upload, so users should check that list before repeating the upload.
- An outage prevents uploads. Its cause and duration are unknown. Contact the archive team is a working help link.
Those facts, including the complete-list behavior, apply only to this example. A real service needs its own verified brief.
| Confirmed state | AI draft | Reviewed wording |
|---|---|---|
| A non-PDF was rejected | “Oops! Your document is broken.” | “Document must be a PDF. Choose a PDF file to continue.” |
| The PDF exceeds 8 MB | “Upload failed. Compress your file by 50%.” | “Document must be 8 MB or less. Choose a smaller PDF file.” |
| The response was lost | “Upload failed. Try again.” | “We couldn't confirm the upload. Check View uploads before uploading the document again.” |
| Uploads are unavailable | “Our server is overloaded. Everything is saved. We'll be back in five minutes.” | “Uploads are unavailable. Contact the archive team for help.” |
The non-PDF message invents damage. The oversized-file instruction invents a reduction that may still leave a file too large. The lost-response message assumes failure. The outage draft invents a cause, persistence behavior, and recovery deadline. A friendlier tone would leave those errors intact.
For either rejection, the form may add: “Your other answers are still in this form. They are not saved if you leave this page.” That accurately describes the example. “Your work is saved” does not.
Check the controls as carefully as the words
Confirm that the named controls exist, are available in that state, and do what the message says. If a real upload list updates slowly or omits completed results, an empty list cannot establish failure. The owner must supply another safe check or explain the limitation.
Google Chat's actionable-error guidance considers the problem, a way forward, and help access. Use those as questions when reviewing a message. A straightforward missing-value error may need one precise correction rather than three formulaic sentences.
Audit reassurance and diagnosis
A tool often supplies a cause to make a message feel finished. “Your connection dropped” is too specific if the system only knows that no result arrived. Atlassian's error-message guidance advises against inventing an unknown reason.
Check reassuring phrases as factual claims:
| Phrase | Question for the owner |
|---|---|
| Nothing was lost | Which information remains, where, and for how long? |
| You haven't been charged | Has the transaction outcome been confirmed? |
| Try again | Is repetition safe and useful for this state? |
| We'll fix it shortly | Is anyone authorized to make that time commitment? |
| Contact support | Is there a working, specific route the user can access? |
An editor cannot diagnose infrastructure from copy. Remove unsupported assertions and ask for missing facts. For sensitive account or transaction states, the responsible team should also establish what information can appropriately be revealed.
Use calm language and exact interface names
Once the state is correct, remove blame, jokes, and technical wording the audience does not need. State the field requirement instead of accusing the user of entering bad data. Keep an error code where it helps support, while giving the user a next step they can understand without decoding it.
Preserve the product's actual control labels. “Open history” creates a needless matching problem when the button says View uploads. The editorial style-sheet guide can help keep names and tone consistent across messages. Grammar and style assistance can refine a verified draft, followed by another check against the brief.
Tone depends on the consequence. An apology may suit a serious service failure; a missing field usually needs a correction more urgently. Do not add “please,” exclamation marks, or apologies by formula.
Review the implemented state
A good string still needs to appear at the right time and connect to the right field. W3C's error-identification explanation addresses identifying detected input errors and describing them in text. Its error-suggestion explanation addresses known corrections, including an exception where disclosure would undermine security or the content's purpose.
Ask the implementation owner to demonstrate the triggers in an authorized review environment. Check that:
- Each message matches the actual condition and preserves an unknown outcome.
- The named field and next action can be identified.
- Retained-input statements hold when the user stays, leaves, and returns.
- Correction and help links reach the intended result.
- Versions of the same error do not contradict one another.
- Keyboard and assistive-technology users receive the message appropriately.
The W3C forms-notification tutorial supplies implementation examples. Copy review alone does not certify accessibility. For surrounding help text, use the screen-reader navigation guide.
Store approved wording with its trigger, evidence, and unresolved questions. Record whether review covered copy alone or also included demonstrated behavior. Only label the rendered state verified after somebody has checked it.
Common questions
Does an error need to explain its cause?
Only when the cause is established and useful. A verified problem statement and recovery action are better than a plausible diagnosis.
Is “try again” ever useful?
Yes, when retry is the confirmed recovery action. It is incomplete if input needs changing first and inappropriate if the previous outcome needs checking.
Can an error code supply enough context for an AI draft?
Usually it cannot establish the user's outcome, retained input, or available controls by itself. Provide a verified state brief, inspect the wording, and review the implemented state before approval.
