Error messages AI agents can understand and 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.

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. For 429s and agents, see rate limits for 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 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.

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.

For more on the forms themselves, see how to make checkout work for AI shopping agents and sign-up, booking and lead forms AI agents can finish.