When the Form Fails: Review AI-Written Error Messages

An error message is useful only when it accurately identifies the problem and helps someone recover. Before AI drafts the sentence, give it a verified error state, an approved next action, and firm boundaries around what the interface may reveal.

“Something went wrong” is vague. “Your file contains malware” may disclose more than the product can safely establish. “Try again” is misleading when another attempt cannot work. A polished model-generated sentence can fail in all three ways while sounding calm and professional.

This workflow is for teams reviewing AI-assisted error and validation copy. It covers public-facing messages, not the underlying controls. Accessibility, privacy, security, sector, and legal requirements vary, so apply the standards and review processes governing the actual service.

An Error Message Is A State Contract, Not A Tone Exercise

The sentence users see sits at the end of a product decision. The system detected a state, the interface handled the submission, and recovery may be available. Some facts may be safe to disclose; others belong only in controlled logs.

An AI tool cannot discover those facts from “make this error friendlier.” It may infer a cause, promise saved work, suggest an unsupported action, or expose an internal exception. The result can be fluent but operationally false.

The NIST Generative AI Profile treats confabulation as a characteristic risk of generative systems: output can be confidently wrong or inconsistent with its inputs. For error copy, the practical control is straightforward. The system and its owners establish the state; AI may draft language inside that established record.

Start With The State, Not The Sentence

Create one error-state record before requesting copy. Give each state a stable identifier so the design, code, tests, support material, analytics, and published message refer to the same event.

Do not let the copy become the only place where these decisions exist. If nobody can confirm whether other answers remain saved after an upload failure, the message must not claim that they are saved. Resolve the product behavior or remove the promise until it can be verified.

Constraints should have one authoritative source. Do not copy file limits, accepted formats, password rules, availability, retry limits, or eligibility independently into code, support content, and prompts. A message built from a stale limit can be clear and still wrong.

Classify The Failure Before Choosing A Pattern

Not every interruption is a field-level validation error. Classification determines the placement, detail, action, and review needed.

1. Missing or unacceptable input: the person can correct a known field or value, such as an omitted name, unsupported file format, or value outside an allowed range.
2. Permission or eligibility: the person cannot complete the action under the current account, role, policy, or service rules. This usually needs an explanation or alternative route rather than instructions to “fix” valid input.
3. Transient service failure: the user’s input may be acceptable, but a dependency, network, capacity limit, or internal process prevented completion. Recovery may involve waiting, retrying, or using another channel.
4. Conflict or changed state: the underlying record changed, expired, or was completed elsewhere. The interface should explain the current state and the safe choices instead of blaming the last action.
5. Security-sensitive rejection: the system blocked an action, but revealing its precise rule, evidence, account status, or internal structure could create risk. Public copy and controlled diagnostics need separate designs.

The GOV.UK Design System error-message guidance makes a useful distinction: a validation message is for input the user can correct. Ineligibility, lack of permission, service capacity, and other problems outside the user’s control require a different pattern with useful next-step information.

The correct component depends on the service and its design system. Copy should never present a service failure as a typing mistake or ask someone to repair a condition they cannot change.

Write For Identification And Recovery

WCAG 2.2 Success Criterion 3.3.1 requires automatically detected input errors to be identified and described in text. Success Criterion 3.3.3 calls for known correction suggestions unless providing them would jeopardize security or the purpose of the content.

A practical message therefore answers three questions when the verified state permits it:

“File is invalid” identifies neither the relevant constraint nor a reliable correction. “Choose a PDF, DOCX, or TXT file” names the action and accepted formats. “Password error” is weaker than a message that states the unmet verified requirement. “Request failed” should not become “Check your internet connection” unless the service actually knows the connection caused the failure.

Match the wording to the field or action label so the message remains understandable away from its visual position. Prefer direct, neutral language over blame, jokes, or emotional performance. An apology does not replace a recovery step, and “please” does not make an impossible action possible.

Specificity has a boundary. Withhold values, rejection rules, or account facts when disclosure creates security, privacy, abuse, or product-integrity risk. Provide the safest useful action instead.

Put The Message Where People Can Use It

Good wording cannot repair inaccessible implementation. The error needs to be programmatically associated with the relevant field or control, exposed in text rather than color alone, and discoverable after submission. When several fields fail, users may need both a summary and a message beside each affected field.

The GOV.UK validation guidance recommends matching inline and summary messages, moving focus to the summary after validation, and preserving both passing and failing answers. It also advises against clearing fields when showing an error. These practices reduce re-entry and make the route back to the problem easier to understand.

Test accessibility patterns in the actual component. Focus, announcements, field associations, summaries, and dynamic messages interact with the framework and assistive technology. Pair copy review with the implementation checks in the related accessibility pass for AI-assisted writing.

Preservation claims require the same discipline. Say “Your other answers are saved” only when the tested product state guarantees it. If the failed action discarded a file but retained the rest of the form, state that distinction only when it materially helps recovery.

Separate Public Copy From Internal Diagnostics

An exception message written for developers is rarely safe or useful public copy. It may reveal a framework version, file path, database structure, query, storage location, account status, security rule, or dependency name. It may also be too unstable to support a durable user instruction.

The OWASP Error Handling Cheat Sheet warns that unhandled errors can expose technical information useful for reconnaissance. It recommends controlled error handling in which users receive an appropriate generic response while detailed evidence is captured through logging.

Generic does not have to mean useless. “We could not check your file. Try again in a few minutes” can be both safer and more actionable than a raw scanner exception. The internal record can separately contain the scanner response, service version, request trace, retry status, and timestamp.

If a public message includes a reference code, confirm support can use it and that it encodes no sensitive data. Treat logs as sensitive records: limit collection, access, and retention, and keep production traces and personal data out of unapproved AI services. The same boundary applies in the privacy checklist for AI-assisted writing.

Give AI A Bounded Drafting Job

Once the state record is approved, AI can propose concise variants, align related messages, or flag inconsistent terminology. Supply the verified facts rather than raw logs. Require the model to expose missing information instead of filling it in.

Task: Draft user-facing error-message candidates for the approved state records below. Do not diagnose the system or change product behavior.

Inputs: State ID, exact interface label, verified trigger, safe public facts, preserved or discarded data, approved recovery actions, prohibited disclosures, voice guidance, and length constraints.

Rules: Produce one message per state. Identify the affected object using its approved label. Describe only the verified problem. Give a correction or next action only when the state record supports it. Do not invent a cause, promise, timeline, saved state, permission, eligibility decision, or support channel. Do not expose internal codes, paths, versions, security rules, personal data, or raw exceptions. Mark missing facts as [REVIEW: question].

Output: Return the state ID, proposed message, facts used, and unresolved questions. Do not claim that the message is accessible, secure, tested, or approved.

The prompt constrains drafting; it does not validate the interface. A human reviewer must compare each candidate with the state record, and the implemented message must be tested by triggering the actual failure.

Worked Example: One Failed Upload, Five Different States

A team begins with one universal message: “Upload failed. Please try again.” Support tickets show that people retry files that can never succeed, while a temporary scanning outage looks identical to a format problem. Engineering and content build the following matrix before rewriting the copy.

The five messages differ because the states differ. The type and size failures can reveal exact correction criteria. The temporary service failure can suggest a retry because the dependency marked it retryable. The saved-state sentence is permitted only because the team verified that behavior. The security rejection omits the rule while still providing an approved route forward.

Another service may use different formats, limits, or security disclosures. Derive every sentence from the product’s real state and threat model.

The team then triggers all five states in the implemented form. It discovers that the scanning failure preserves text fields on desktop but clears them on mobile. That is a product defect, not a wording problem. Until the behavior is fixed and retested, the message cannot promise that other answers are saved.

Test The Whole Recovery Path

Reviewing a copy document is not enough. Use the same literal execution principle as the procedure dry-run workflow: create each failure, observe the interface, follow the stated action, and confirm the resulting state.

1. Trigger every state using a documented test case rather than a mocked screenshot alone.
2. Confirm that the implemented state ID selects the intended message.
3. Verify every format, size, date, limit, label, and next action against the authoritative product source.
4. Check that the message does not infer a cause the system cannot establish.
5. Confirm that passing and failing values are retained or cleared exactly as the copy states.
6. Verify that inline messages are associated with the correct fields and that errors are described in text, not color alone.
7. When a summary is used, confirm that focus reaches it and its links move to the correct controls.
8. Complete the flow by keyboard and with representative screen-reader testing.
9. Test narrow screens, zoom, text resizing, long labels, and supported languages.
10. Follow every retry, replacement, cancellation, support, and alternate-channel action to its real destination.
11. Test timeouts, repeat submissions, offline transitions, changed permissions, and dependency failures according to risk.
12. Inspect the public response for stack traces, paths, versions, internal rules, identifiers, and personal data.
13. Confirm that controlled logs capture enough evidence to investigate the state without relying on the user-visible sentence.
14. Re-run affected states after any change to validation logic, limits, components, routing, or message text.

Automated tests can verify state-to-message mappings, constraints, links, and selected accessibility properties. Human testing remains necessary for clarity, context, focus order, assistive-technology behavior, and whether the proposed recovery actually makes sense.

Set A Human Release Gate

No single reviewer can establish every part of an error message. Assign approval according to consequence.

Low-impact copy may combine several roles. Account recovery, payments, health, legal rights, identity, sensitive uploads, and irreversible actions may require independent or specialist review. These are routing decisions for the organization, not certifications an AI tool can issue.

Record the approved message with its state ID and authoritative constraints. If a limit or recovery route changes, route the affected messages back through review. Do not assume that a grammatically unchanged sentence remains correct after the underlying product changes.

Use Production Evidence To Improve The Journey

Track error frequency, repeated attempts, successful recovery, abandonment, support contacts, and state changes when policy and privacy controls allow it. A message viewed thousands of times may reveal a product problem that copy alone should not normalize.

If users repeatedly exceed a hidden limit, expose the limit before submission. If a required format is hard to produce, reconsider the input design. If a dependency fails frequently, fix reliability rather than testing warmer apologies. Use production evidence to improve the journey, and collect only the data needed for that purpose.

A Message Is Ready Only When Recovery Is Real

Reliable error copy begins with reliable state knowledge. The system identifies the condition. Product and engineering define what happened. Accessibility and security shape how it is communicated. AI can then help draft concise variants, while a human owner verifies the sentence against the implemented experience.

The goal is not to make failure sound human. It is to help a real person understand what happened, find the right place, and take an action that genuinely works without exposing information that should remain protected.