Error Bodies a Model Can Parse and Act On

RFC 9457 defines a JSON object with five members: type, title, status, detail and instance, plus extension members, and it explicitly says its purpose is to carry machine-readable details of errors so APIs do not each define a new format (RFC 9457). That is the right substrate. What it does not define is the set of fields a model needs to choose an action, so treat the standard as the outer shell and add the agent fields as extensions.

Spring Framework's implementation shows how cleanly this works in practice: its ProblemDetail type is "a simple container for both standard fields defined in the spec, and for non-standard ones", and its Jackson integration unwraps a properties map so extension fields render as top-level JSON (Spring Framework docs). You do not need Spring to copy the idea, only the discipline of one container with two layers.

Two design rules follow from the table. First, code must be stable and documented: a string like invalid_currency survives a change to the human message, while a bare number such as 1 does not. Speakeasy's design guide makes the case directly, showing a response that improves from a bare "Trip is not possible" message to one with "code": "trip_not_possible", which lets a client write if (error.code === 'trip_not_possible') instead of matching on prose (Speakeasy). Second, retryable must be explicit even when it looks obvious. Temporal's cookbook, which parses HTTP responses into retry policies, lists 408, 409, 429, 500, 502, 503 and 504 as retryable and 400, 401, 403, 404 and 422 as not, but it also honors a non-standard X-Should-Retry header that overrides the status code when the server knows better (Temporal). Put that override in the body, where the model will actually read it.

Here is the shape to standardize on. Every non-2xx response, from any endpoint, from any service behind your gateway, returns exactly these top-level keys. Extra keys are allowed, missing ones are not.

{
  "type": "https://api.example.com/problems/currency-not-supported",
  "title": "Currency not supported",
  "status": 422,
  "code": "currency_not_supported",
  "message": "The 'currency' field must be one of the supported ISO 4217 codes.",
  "retryable": false,
  "retry_after": null,
  "docs_url": "https://docs.example.com/errors/currency_not_supported",
  "request_id": "req_01J9ZK4M8Q2C7R3V6B1N5TXW4A",
  "details": [
    {
      "field": "currency",
      "pointer": "#/payment/currency",
      "issue": "not_in_enum",
      "allowed": ["USD", "EUR", "GBP", "JPY"],
      "received": "USDT"
    }
  ]
}

Notice three deliberate choices. The type is a URL under your control, which RFC 9457 recommends so that a problem type can be documented and dereferenced (RFC 7807); the separate code is a short string because models copy short strings more reliably than long URLs into a condition. The retry_after key is present and null rather than absent, so a model that reads the field always finds it and does not fall back to "maybe it is in a header". And details carries a pointer, a JSON Pointer, so the model can point at exactly the sub-object to fix instead of re-sending the whole document.

The Swagger guide on doing API errors well makes the general case: custom error formats are one of the biggest sources of friction in integrations, and the challenges multiply with AI consumers that need precision rather than a paragraph (Swagger). A single envelope is the cheapest way to get that precision, because it makes the agent's error handler a single function.

Status codes alone under-determine the action, which is why the same 4xx can mean "fix your request" or "wait and try again". Below are worked payloads for the cases where agents most often pick the wrong branch.

404, but the resource is on its way. A 404 normally means stop: the thing does not exist. That is wrong for a resource created asynchronously a moment ago. Encoding "not yet" as a retryable 404 is the fix, and it is exactly the case Cloudflare handles by telling the agent whether to retry or escalate via an owner_action_required field (Cloudflare).

{
  "type": "https://api.example.com/problems/not-ready",
  "title": "Resource not ready",
  "status": 404,
  "code": "resource_not_ready",
  "message": "The export is still being generated. Poll again shortly.",
  "retryable": true,
  "retry_after": 5,
  "docs_url": "https://docs.example.com/errors/resource_not_ready",
  "request_id": "req_01J9ZK5A1B7D9E2F4G6H8J0K2L",
  "details": []
}

429, where the wait matters more than the status. The rate-limit case has a standard header, Retry-After, and a well-formed 429 should carry it alongside a Problem Details body (Zuplo on 429). Duplicate the seconds into retry_after in the body. Not every client surfaces headers to the model, and a model that reads "30" in the body will wait 30 seconds rather than invent a backoff.

{
  "type": "https://api.example.com/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "message": "Rate limit exceeded for this key. Retry after the indicated delay.",
  "retryable": true,
  "retry_after": 30,
  "docs_url": "https://docs.example.com/errors/rate_limited",
  "request_id": "req_01J9ZK6B2C8E0F3G5H7J9K1L3M",
  "details": [{ "field": "limit", "issue": "exceeded", "scope": "api_key", "window_seconds": 60 }]
}

401 versus 403, the classic wrong branch. Agents routinely retry a 401 with the same key, which cannot work, or give up on a 403 that only needed a different scope. Temporal's list treats both as non-retryable, and that is right for the request as sent, but the recovery differs and the body should say so (Temporal). For a 401, set retryable: false and put the refresh action in message. For a 403 that is scope-related, include the required scope in details so the agent can request the right grant instead of stopping.

{
  "type": "https://api.example.com/problems/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "message": "This token lacks the 'exports:write' scope. Request a token with that scope or use a read-only path.",
  "retryable": false,
  "retry_after": null,
  "docs_url": "https://docs.example.com/errors/insufficient_scope",
  "request_id": "req_01J9ZK7C3D9F1G4H6J8K0L2M4N",
  "details": [{ "field": "scope", "issue": "missing", "required": "exports:write", "granted": ["exports:read"] }]
}

500 and 503 are not the same. Both are server-side, but a 500 may hide a bug the client triggered, while a 503 is a temporary capacity problem. Cloudflare's 1xxx class shows the useful shape: classify the failure with error_code and error_category, then let retryable and retry_after drive the backoff (Cloudflare). For a 500 you did not expect, say so in the message and set retryable: true with a short delay, because a single retry costs little and often clears a transient dependency failure.

The most useful decision rule is a precedence order: trust the body before the status code, and the status code before the agent's own judgment. A retry loop in an agent should look like this, in order:

1. If retryable is false, stop and surface the message and docs URL to the user or the planning step.
2. If retryable is true and retry_after is a number, sleep that long exactly, then retry.
3. If retryable is true and retry_after is null, fall back to exponential backoff with jitter.
4. After N failures, stop and include request_id in the escalation.

That precedence is worth writing down because the cheap version, retry every 5xx and give up on every 4xx, gets two important cases wrong. It retries a 503 with fixed spacing and causes a thundering herd, and it gives up on a retryable 404 that would have resolved in five seconds. PostGrid's retry documentation recommends capping at five attempts spread over a 30-minute window using exponential backoff with full jitter, where the actual delay is a random value between zero and the calculated delay, and pairing retries with idempotency keys so a repeated create does not duplicate an order (PostGrid). The body cannot carry the idempotency decision for the client, but it can and should carry the delay.

There is a scaling point hidden here. Every field you add to the error body is paid on every failure, across every step of every workflow. Cloudflare's experience with a 1015 rate-limit page, where structured JSON and Markdown cut token usage by more than 98% against HTML, is the argument for stripping CSS and copy but keeping retryable and retry_after (Cloudflare). A 300-token JSON body with five useful fields beats a 40,000-token HTML page that says "blocked".

Idempotency also changes what "retryable" can honestly mean. An error on a non-idempotent POST is not safe to retry just because it was transient; the request may have landed. The honest body for that case sets retryable: false and says "check the resource before retrying" with a link to the endpoint that lists recent creations. That is a decision rule most first-page error guides miss.

An agent does not only consume your errors. It also produces errors of its own, from the model call that grounds its plan or the tool that turns text into a call. If the agent's internal failures use a different shape from your API's, the agent's own error handler becomes the second place you have to maintain parsing logic. Return them in the same envelope.

This is where an inference layer earns its keep. If an agent calls several model providers, each with its own error format, rate-limit behavior and quota semantics, normalizing them is the same job as normalizing your own API errors: one code, one retryable flag, one delay. Quanta Inference exposes text, image, video, audio and embedding models through a single OpenAI-compatible API key, which means one error shape to normalize rather than one per provider (https://quantaintelligence.ai/inference). Whatever you pick, write the normalization once, at the boundary, and hand the model a body it can read.

Two practical checks before you ship. First, verify your client library does not discard the body on error, which is the failure Pol Alvarez Vecino describes with HTTP Error 422 (Pol Alvarez Vecino). Second, test the body with the model that will actually read it: give it the payload and the tool schema and ask which action it would take, then check it against your intent. If it retries a 403, the message was too vague.

Here is the checklist to run against every endpoint before you call the error model done.

The leak check is not cosmetic. Spring's own documentation notes that it is good practice to customize problem details for framework exceptions specifically to avoid revealing implementation details (Spring Framework docs). A model will happily repeat an internal hostname back to a user in its answer.

A worked example makes the value concrete. Suppose an agent submits an order with three problems: a missing email, a currency outside the enum, and a duplicate client reference. A single-error 400 forces three round trips, and each one spends input tokens re-sending the whole request. A single 422 with three details entries lets the model fix all three and one request attempts the call again. That is the option the Stack Overflow discussion on error return structure converges on: return the full list of field problems rather than stopping at the first, because it saves requests and lets the client revalidate only what changed (Stack Overflow). Doing the same math on a 30-step agent workflow with an average of two validation failures per step, you save roughly 30 extra round trips per run, and every saved trip is one fewer set of tokens.

Finally, version the error contract like any other interface. API versioning exists to manage change without breaking consumers, and an error schema is part of what a consumer depends on (Akamai). If you need to add a field, add it. If you need to change the meaning of retryable for an existing code, introduce a new code. An agent that has learned the old code from a schema or a docs page should not silently change behavior because you edited a message string.