Error Docs an AI Agent Can Actually Recover From

A developer asks a coding agent to integrate your API. The first authenticated request comes back as a 422 with a one-word message. Your docs list the status code and nothing else. The agent does what agents do with a gap in the docs: it fills the gap. It renames a field it decides is probably wrong, invents a parameter that sounds plausible, retries with confidence, and keeps going until something returns a 200 or the developer gives up and files a support ticket. The ticket blames your API, because from where the developer sits, your API is what failed.

That failure mode is the reason API error documentation deserves more attention than it gets. Human developers who hit an undocumented error open a browser tab and go searching. An agent has no tab to open. It has your error response, whatever your docs said about it, and a strong prior toward producing an answer. Missing error docs don't make an agent stop — they make it guess, and it guesses fluently. Good error documentation converts failures into recoveries. Bad error documentation converts them into support tickets with your name on them.

Discry measures a version of this directly. The Discry methodology includes trap tasks: tasks that ask a model to do something the API doesn't support, where the correct answer is a refusal and the failing answer is a confident invention. Error handling is the same test administered at runtime. When your API says "no" and your docs don't say why, the model's options are refuse or invent — and invention is what models are good at.

The loop an agent runs when a request fails

An agent recovering from a failed API call works through a short loop, and every step of it is either a documentation lookup or a guess:

1. Classify the failure. What does this status code and error body mean? Is this my fault (a malformed request), the caller's fault (bad credentials, exhausted quota), or the server's fault (transient outage)?
2. Decide whether to retry. Is this error retryable at all? A timeout might be. A validation failure never is — retrying the identical request produces the identical rejection.
3. Decide what to change. If the request was wrong, which part? A field name, a value format, a missing header, an expired token?
4. Retry or escalate. Either send a corrected request, wait and resend an identical one, or stop and report the failure upward.

With good error docs, each step is a lookup: the error body carries a machine-readable code, the code appears in a catalog, the catalog row says what caused it and what to change. Without them, each step is a guess — and guesses compound. An agent that misclassifies a validation error as transient will retry the same broken request into your rate limits. An agent that can't tell which field failed will mutate fields one at a time, burning requests and tokens on an experiment your docs could have answered in one sentence.

Both patterns show up throughout the audit corpus behind the Discry Index. Some APIs document only their 200 responses — no error codes, no error schema, no recovery guidance — so an agent learns how failures behave exclusively by failing. Others document errors as bare status-code lists: an agent hitting a 422 learns that "the entity couldn't be processed" and nothing about which field, which validation, or what a corrected request looks like. The pattern we flag most often in scan findings is exactly this gap between parseable and recoverable: errors that return typed JSON with a message, while the docs stop at descriptions like "Not found" without telling an agent what to change to succeed on the next attempt.

Anatomy of an error response an agent can recover from

A recoverable error response answers the loop's questions in the response itself. Five parts, in rough priority order:

• An accurate HTTP status code. The coarse classification: 400-class means the request is wrong, 401/403 mean identity or permission, 429 means slow down, 500-class means the server. Agents key their first branch off this, so a 200 that carries an error in the body is actively hostile — it defeats the classification step entirely.
• A stable, machine-readable error code. A string like card_declined or parameter_missing that an agent can match exactly, look up in your catalog, and branch on. Messages get reworded; codes are a contract.
• A human-readable message that names the problem precisely. "Invalid request" recovers nothing. "starting_after must be an object ID, received an integer" is a fix instruction disguised as an error message.
• A pointer to documentation. A URL for this specific error type, so an agent (or the developer reading the agent's transcript) can pull the full recovery context.
• Retry semantics. Whether this error is retryable, and if so, when — a Retry-After header on 429s and 503s, or an explicit retryable flag in the body.

You don't have to invent a format for this. RFC 9457, "Problem Details for HTTP APIs" — the standard error response format, served as application/problem+json — defines exactly this shape: a type URI identifying the problem class, status, a short title, a detail string explaining this occurrence, and an instance URI, with room for extension members like a field name or a retry hint. A problem-details response for the 422 that opened this article looks like:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "amount must be a positive integer in minor units; received \"49.99\"",
  "instance": "/v1/charges",
  "invalid_params": [
    { "name": "amount", "reason": "expected integer (minor units), got decimal string" }
  ]
}

Every member is doing recovery work: the type URI is the docs pointer, detail names the fix, and invalid_params tells the agent which field to change — so the corrected retry happens on the second request instead of the ninth. Naming the exact bad parameter in the error body is one of the strongest patterns we see in the wild: Instacart's error schema returns a code plus a meta.key naming the offending parameter with a prescribed corrective action, and Square's errors carry category, code, detail, and field — machine-parseable down to the thing that needs to change.

An error catalog is a decision table

The response tells an agent what happened. The catalog — the errors page in your docs — tells it what to do next. The pattern that works is a decision table: one row per error code, with columns for the HTTP status, the cause, the fix, and whether it's retryable. A worked slice:

Code	HTTP	Cause	What to change	Retryable
authentication_failed	401	Key missing, malformed, or revoked	Check the Authorization header format; issue a new key if revoked	No
insufficient_scope	403	Key is valid but lacks this permission	Request the scope; do not retry with the same key	No
parameter_invalid	422	A named field failed validation	Fix the field named in invalid_params, resend	After fixing
rate_limited	429	Request budget exhausted	Wait Retry-After seconds, then resend unchanged	Yes, after delay
internal_error	500	Fault on our side	Resend with exponential backoff; contact support if persistent	Yes

That last column is the one agents need most and get least. Explicit retryable-vs-non-retryable rulings are what separate the strongest error docs in the corpus from the merely complete ones. Firecrawl's errors page maps every error to cause → remedy → retryable, with a copy-pasteable backoff snippet. Together AI documents an explicit cause and fix for every status code from 400 through 529. monday.com's error reference is a structured table mapping each code to its HTTP status, description, and an explicit resolution column. Courier's responses page gives every status an action column plus a validation-errors table in error → cause → fix form. Temporal goes furthest: a dedicated error-handling guide with retryable-vs-non-retryable decision rules and idempotence design, written for exactly the self-correction loop this article describes. None of this is exotic — it's the same table, kept honest.

What to document, failure by failure

Four failure families cover most of what an agent will actually hit. Each has one question your docs must answer.

Auth failures. The question is which auth problem. A 401 for a missing key, an expired token, and a malformed header are three different fixes, and an agent that can't distinguish them will regenerate credentials when it should have fixed a header. Document your exact header format with a literal example, the difference between your 401 and your 403, token lifetime and the refresh flow, and what an expired token error looks like versus a revoked one. See the glossary on API authentication for the shapes agents encounter.

Rate limits. The question is when to come back. Document the limits themselves, the headers that expose remaining budget, and — critically — that you send Retry-After (a standard HTTP header) and that clients should honor it with exponential backoff rather than hammering. An undocumented rate limit turns a well-behaved agent into a DoS participant: it hits the 429, has no guidance, and retries on its own schedule.

Validation errors. The question is which field. A 422 that names the parameter, the expected format, and the received value is self-correcting; a 422 that says "unprocessable entity" is a mutation loop. If your error body carries structured field-level detail, document the schema of that detail — it's the most valuable schema in your reference.

Idempotency conflicts. The question is is it safe to resend. Timeouts are where agents do real damage: resend a payment that actually succeeded and you've charged someone twice. Document your idempotency key mechanism, key expiry, and what happens when a key is reused with a different payload. lemon.markets ships a dedicated idempotency guide covering retry-safety, key expiry, and a full error-scenario table — precisely the guidance that lets an agent recover from a timeout without duplicating an order — and its profile shows how far that carries even where other signals lag.

Error docs are comprehension surface

In agent-readiness terms, error documentation sits on the comprehension side: it's part of whether an agent can operate your API from what you've published, and the Discry scan quizzes models on exactly these facts — auth, errors, limits — against your live docs. It also touches discovery: an errors page that exists but isn't routed from your llms.txt is an answer the agent never finds, and your AGENTS.md is the natural place to flag the two or three errors integrators hit first. If you're sequencing fixes, the prioritized checklist puts error-recovery guidance in context with the rest.

The economics favor you here. An error catalog is a table; retry semantics are a column; a Retry-After header is a few lines of middleware. Against that cost, every recoverable error is an integration that finishes instead of a ticket that arrives — and agents, unlike humans, follow the recovery instructions exactly as written, every time.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.