# Error messages AI agents can understand and fix

> Help AI agents recover from mistakes: error text tied to each field, live regions, useful 404 pages and HTTP status codes that match what the page says.

Published October 9, 2026 by Ghost Agent Labs · Navigability · https://ghostagentlab.com/articles/error-messages-ai-agents/

## Key takeaways

- AI agents can only fix a form mistake if the error is written in text, says what to do, and sits beside the right field.
- An unclear error can quietly end a journey, so you lose the order or sign-up without anyone telling you.
- Start by submitting your checkout with a wrong ZIP code and checking whether the page text alone explains what to fix.

Every journey hits an error eventually: a mistyped postcode, a promo code that's expired, a product that's gone. A person reads the red text, fixes it and carries on. An AI agent can only do the same if the error is written down, attached to the right field and reported honestly by your server. Otherwise it tries again, gives up, or tells the shopper something went wrong without saying what.

## Why errors matter more for agents

An agent working for someone wants to finish the task. When a form doesn't go through, it needs to answer three questions: did something go wrong, which field caused it, and what should it enter instead? People answer those from visual cues, such as a red border, a shake, an icon or a message that flashes up and disappears. Agents mostly read the page's text and structure, and may not catch any of those cues.

A clear error turns a failed attempt into a quick correction. An unclear one ends the journey, and you lose the order or sign-up without anyone telling you. The same fixes help people who use screen readers, and anyone filling in a form on a small screen.

## Write errors that say what to do

Start with the words. An agent passes the message on, or acts on it, exactly as written.

| Unhelpful | Helpful |
| --- | --- |
| Invalid input | Enter a 5-digit ZIP code, like 10001 |
| Error | This email address is already registered. Log in or reset your password. |
| Promo code not applied | The code AUTUMN10 expired on September 30 |
| Something went wrong | We couldn't save your address. Please try again in a minute. |

- Name the field and the problem, and give an example of what's accepted.
- Say whether it's something the shopper can fix, or something on your side that may work later.
- Don't rely on color, icons or a border alone. If it isn't in text, assume an agent won't see it.
- Keep what was entered. Clearing the whole form after one mistake makes an agent start again, and some won't.

## Tie each message to its field

An error floating near a form isn't enough. Agents, like screen readers, need to know which field it belongs to. Two attributes do that:

```
<label for="zip">ZIP code</label>
<input id="zip" name="zip" autocomplete="postal-code"
       aria-invalid="true" aria-describedby="zip-error">
<p id="zip-error">Enter a 5-digit ZIP code, like 10001</p>
```

- `aria-invalid="true"` marks the field as having a problem. Remove it once the value is fixed.
- `aria-describedby` links the field to its message, so the message is read as part of the field's description.
- Put the message in the page as text next to the field, not in a tooltip that only appears on hover.
- For required fields, use the `required` attribute, and the right `type` and `autocomplete` values, so agents can get it right first time. Labels matter here too: see [buttons, links and forms agents can use](https://ghostagentlab.com/articles/agent-friendly-buttons-forms/).

## Summarize errors and announce changes

On a long form, such as checkout or account sign-up, add a short summary at the top when it's submitted with problems. It lists each error as a link to its field, and gets keyboard focus so it's the first thing read.

```
<div role="alert" tabindex="-1" id="error-summary">
  <h2>There are 2 problems with your details</h2>
  <ul>
    <li><a href="#zip">Enter a 5-digit ZIP code, like 10001</a></li>
    <li><a href="#phone">Enter a phone number with area code</a></li>
  </ul>
</div>
```

For messages that appear without a page load, such as "Promo code applied" or "Only 2 left, quantity updated", use a live region. `role="alert"` is for urgent errors. `role="status"` or `aria-live="polite"` is for confirmations. Keep the message on screen until the next action: toasts that fade after three seconds are easy for an agent to miss.

## Make error pages say what happened

Errors aren't only in forms. When an agent follows an old link or a product is discontinued, your error page is what it reads. It should explain, and offer a way forward.

- **Not found pages** should say the page doesn't exist, and include a search box and links to main categories, so an agent can recover.
- **Discontinued products** are better served by a page that says so, with links to alternatives, or a permanent redirect to the closest replacement.
- **Out-of-stock products** should keep their page, show "Out of stock" in text, and set `availability` to `OutOfStock` in your product data. Don't turn them into errors.
- **Server errors and maintenance** pages should say it's temporary and, if you can, when to try again.

## Send the status code that matches

Agents and crawlers read your HTTP status code before they read a word of the page. If they disagree, the code usually wins. A "Page not found" message sent with a `200 OK` status, often called a soft 404, tells crawlers the page is fine, so the dead page may stay in AI search answers. A real product page that returns an error tells them it's gone.

| Situation | Status code |
| --- | --- |
| Page loaded normally, including out-of-stock products | `200` |
| Page moved for good | `301` or `308` to the new address |
| Page doesn't exist | `404` |
| Page removed on purpose and not coming back | `410` |
| Too many requests | `429`, with a `Retry-After` header |
| Something broke on your side | `500` |
| Down for maintenance or overloaded | `503`, with a `Retry-After` header |

Two common mistakes: redirecting every missing page to the home page, which leaves agents on a page that doesn't answer the question, and serving a block page with `200`, which looks like content. The meanings of these codes are defined in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110). For 429s and agents, see [rate limits for AI agents](https://ghostagentlab.com/articles/rate-limits-ai-agents/).

For form submissions, what matters most is that the page sent back shows the errors in text, tied to their fields. Whether you re-render the form with `200` or use `422` is less important than making the message clear.

## What AgentScore and Ghost Agents show

AgentScore doesn't have a check for error messages, since it never submits your forms. Several checks cover the groundwork. "Form fields are labelled" checks the home page's fields, and "Cart and checkout fields are labelled for agents" checks the cart and checkout. "AI agents can open your product, pricing and cart pages" compares the status codes AI assistants get with what a browser gets, which catches bot protection sending agents errors that people never see.

To see what happens when an agent actually makes a mistake, run a journey. A [Ghost Agent](https://ghostagentlab.com/ghost-agent/) types the test details you give it and records each step, so if a form rejects them without saying why, the replay shows exactly where it stalled. Ghost Agents stop at the payment form, so payment errors are out of scope. To find the errors agents hit in real traffic, see [finding the errors AI agents hit in your logs](https://ghostagentlab.com/articles/agent-errors-in-logs/).

## A quick checklist

1. Every error message says what's wrong and how to fix it, in text.
2. Each field with an error has `aria-invalid="true"` and `aria-describedby` pointing to its message.
3. Long forms show an error summary that links to each field.
4. Messages that appear without a page load use a live region and stay on screen.
5. Entered values are kept after an error.
6. Missing pages return `404` or `410`, with a search box and useful links.
7. Out-of-stock products keep their page, with a `200` status.
8. Maintenance and rate-limit responses use `503` or `429` with `Retry-After`.

> **Try it yourself.** Submit your checkout's address form with a wrong ZIP code, then read only the text on the page. If you can't tell which field is wrong and what it wants, neither can an agent.

For more on the forms themselves, see [how to make checkout work for AI shopping agents](https://ghostagentlab.com/articles/agent-ready-checkout/) and [sign-up, booking and lead forms AI agents can finish](https://ghostagentlab.com/articles/agent-friendly-sign-up-booking/).

## Sources and further reading

- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) (IETF)
- [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585.html) (IETF)
- [Understanding WCAG 2.2 Success Criterion 3.3.1: Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (W3C)
- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) (W3C)