Error Messages as an Agent Interface: Designing API Failures an Agent Can Recover From

Your API returns 400 Bad Request with the body {"error": "invalid input"}. A human developer opens the docs in a second tab, compares the payload against the schema, and fixes it in under a minute. An AI agent has no second tab. It has the request it sent, the string you sent back, and a decision it has to make right now.

So it guesses. It reorders fields. It retries the identical call in case the failure was transient. It renames user_id to userId, then back again. Every guess is a round trip and a few thousand tokens of context, and the run ends with the agent telling your user that your API is down.

The fix is not better docs. Agents read docs once, at plan time, and then operate on whatever comes back over the wire. The error body is the interface.

What an agent sees when your API says no

For a human, an error message is one input among many — docs, source code, a Slack thread, the last five minutes of memory. For an agent, the error body is close to the entire environment for that step. Whatever bytes you return get appended to the context window, where they function as instructions.

That means every failure response has to answer three questions on its own:

1. Is this my fault or yours? Decides whether the agent edits the request or waits.
2. If it’s mine, what exactly do I change? Decides whether the next attempt is a targeted edit or a random walk.
3. If it’s yours, when do I come back? Decides whether you get a polite backoff or a retry storm.

Status codes answer part of question one and nothing else. 400 covers malformed JSON, a missing scope, a violated business rule, and a field that’s three characters too long — four failures with four different recovery strategies, flattened into one signal. When the signal is that lossy, the model falls back on its prior, which was trained on every badly documented API on the internet.

Five fields that turn a rejection into a repair

Most APIs return a sentence. Agents do much better with a record. A workable minimum shape:

{
  "error": {
    "code": "date_range_too_wide",
    "message": "start_date and end_date must be at most 31 days apart.",
    "retryable": false,
    "field": "end_date",
    "constraint": "end_date - start_date <= 31 days",
    "received": { "start_date": "2026-01-01", "end_date": "2026-06-01" },
    "example": { "start_date": "2026-01-01", "end_date": "2026-02-01" },
    "docs_url": "https://api.example.com/errors/date_range_too_wide"
  }
}

What each field buys you:

• code is a stable enum, not a sentence. Agents pattern-match on it, your own client can switch on it, and your evals can assert against it. Reword a message freely; treat a code change like a breaking API change, because every cached plan and prompt that referenced it breaks silently.
• retryable is explicit. Don’t make a model infer retryability from a status code. 409 vs 422 vs 429 is not consistent across APIs, and whether your 500 is transient depends on infrastructure the agent can’t see. One boolean deletes the guess.
• field plus constraint beat prose. “Invalid input” tells the agent to search. field: end_date tells it where to edit, and constraint tells it what valid means, in a form it can check before spending another request.
• received closes the loop. The agent’s original tool call may be dozens of turns back, or already summarized out of context. Echoing what you actually parsed lets it diff instead of re-deriving.
• example is the highest-leverage field and the one most APIs omit. A valid example payload converts a reasoning problem into a copy-edit.

For 429 and 503, put the wait hint in the body as retry_after_seconds, not only in the Retry-After header. Plenty of agent HTTP wrappers surface the response body to the model and drop headers entirely, so a header-only hint is invisible exactly where it matters.

The shapes that trap agents in loops

The catch-all 400. One code for schema errors, auth scope errors, and business-rule violations forces the agent to try all three recovery paths in sequence. Split it: one code per distinct fix.

429 with no wait hint. Without a number, the agent invents a backoff, and models tend to invent short ones. You’ve turned a rate limit into a retry storm from a client that never gets tired.

Errors that change on every call. Request IDs and timestamps inside message mean two identical failures look like two different problems, which defeats the agent’s own “I already tried that” heuristic and any caching in front of it. Keep varying data in separate fields and keep message byte-stable for a given code.

200 OK with an error in the body. The worst one. The tool wrapper reports success, the model takes the payload at face value, and a wrong value propagates through the rest of the run without ever surfacing as a failure.

“Contact support.” That’s an instruction the agent cannot execute, so it will improvise alternatives — retrying, hunting for another endpoint, or fabricating a workaround. Write terminal errors as explicit stop instructions instead: state that the condition is not recoverable programmatically and that the agent should stop and report to its user.

Testing errors like you test the happy path

Happy paths get integration tests. Error paths usually get a status-code assertion and nothing about whether the response is actionable. For an agent-facing API, that’s the half that decides whether a run completes.

A practical loop: build one fixture per error code, then script an agent — OpenCode, Cursor’s agent mode, whatever your team already runs — to call the endpoint in a way that triggers it, with the docs available. Measure turns to recovery. One turn is the target for anything the caller can fix. Anything above two is a bug in the error message, not in the model.

Two things that make this cheap to maintain: enumerate every code at a public endpoint or in a checked-in errors.json so you can hand the full enum to an agent up front, and generate both your docs and your test fixtures from that same file. Then a new code can’t ship undocumented, and an error string can’t drift away from the tests that assert on it.