For an AI agent using your tool, the error message is the documentation. About 27% of all the friction agents hit is errors — and two-thirds of those are major or critical.
Here's what makes AI agents different from us. A human reads an error, forms a hypothesis, and tries something. An agent takes the message literally and acts on the exact text. A vague error wastes its time; a misleading one sends it down the wrong path entirely.
So the real question for everyone building in the agentic era is: how do you design a great error message? Here's what we learned from ~3,500 Agent Experience (AX) evals across 100+ developer tools.
1. Name the remediation, not just the failure
In ~16% of error friction, the message stated what broke but not what to do about it. The agent knows it failed; it doesn't know the next move.
Rule of thumb: every error should end with the next action.
2. Put the "where" inside the error — a literal URL
Our insights repeatedly surface the same fix: append the dashboard link to the error. Agents burn the most time context-switching to find where they can self-serve. Something as simple as "get a key at https://…/dashboard" inside the message does the job.
Rule of thumb: tell the agent exactly where to go, with a real link.
3. One distinct cause, one named message
Generic errors are probably the worst thing for AX. "Session not found" isn't informative — the agent spends time guessing the right recovery path. Distinguishing the actual cause guides it straight to a quick resolution.
Rule of thumb: one distinct cause → one distinct, named message.
4. Own your errors
This one sounds easier than it is. Servers keep auth errors vague ("unauthorized"), but you can check the input on your side before each call — and you control the message your agentic users receive. Spot a wrong-format key and return "API key should start with xx_" instead of a blank 401.
Rule of thumb: validate the input client-side, and state exactly what's wrong.
5. Make silent failures loud
The most expensive errors are the silent ones. ~9% of all error friction were silent failures — no error at all. These cost the most, because the agent thinks it succeeded and keeps building on a wrong state.
Rule of thumb: if you reject, default, or restrict something, your message needs to reflect that.
6. Offer the headless/CI path
13% of error friction assumes a human is in the loop: interactive-only login, with no token or env-var path mentioned. Agents don't have a browser tab open to click through.
Rule of thumb: always offer a non-interactive way to recover.
Let's ship errors agents can act on
To make all of this easy to apply, we've packaged these best practices into a single skill. You can find it in the 2027.dev skills repo — drop it into your agent and let it audit your error messages against every rule above.
Have a rule we missed, or a great (or terrible) agent error message in the wild? Reach out at mika@2027.dev or DM me on X anytime — @heymikasagi.