Choosing HTTP Status Codes for an Agent-Facing API

The table below is the core of this article. Read it as a contract: the "agent action" column is what a well-written prompt or orchestration framework should do when it sees the code.

The retryable and non-retryable split in this table follows a widely used convention: 408, 409, 429, 500, 502, 503, and 504 are treated as retryable, while 400, 401, 403, 404, and 422 are not (Temporal's HTTP retry recipe). You will notice 409 sitting on the fence. Treat it as retryable only when your API documents that the conflict is a temporary lock rather than a duplicate key, and have the agent re-read state before trying again.

A second reference point comes from payment and mailing APIs that publish their retry policy. One such provider tells clients to retry only 429 and 503, using exponential backoff with jitter and an idempotency key so that a retried create does not produce duplicates (PostGrid retry logic). Narrowing the retry set this aggressively is defensible for create operations, because each retry risks a double side effect.

The decision rule I recommend: retry only codes that a retry can fix, and only on requests you can safely repeat.

Most agent failures are prompt failures. The model does not inherently know that a 503 means "wait" and a 422 means "fix your arguments," so you have to tell it. The most robust pattern is to put the decision table into the system prompt in the same shape as the table above, plus a hard cap on attempts.

You call an external HTTP API. After every call, look at the status code.

If 200-299: continue with the result.
If 400: your request body was malformed. Fix it once and retry. If 400 happens
  again, stop and report the problem detail field.
If 401: call the refresh_token tool, then retry the request exactly once.
  If 401 happens again, stop and ask a human.
If 403: you do not have permission for this operation. Do not retry.
  Choose a different tool or stop and ask a human.
If 404: the resource does not exist. Check the identifier, then change your
  plan. Never retry 404 with the same identifier.
If 409: re-read the resource, then retry once.
If 422: read the "errors" array in the body. Only change the fields it names.
  Retry once. If it fails again, stop.
If 429 or 503: read the Retry-After header. Wait that many seconds, then retry.
  Do not retry more than 3 times in total.
If 500, 502, or 504: wait, then retry. Do not retry more than 3 times.
If any code is not listed above: stop and report it. Do not guess.

Never retry the same request more than 3 times without changing something.

Two things make this work in practice. First, the list of explicit codes gives the model an anchor for the common cases. Second, the fallback rule ("if any code is not listed, stop") prevents the model from inventing behavior for a code you did not anticipate. Without that rule, an agent that receives a 418 or a custom 4xx code will usually retry, because retrying is the safest available default from the model's point of view.

The retry cap matters as much as the mapping. Bounded retry is standard in production agents, where layered failures (model API, tool API, business logic) are handled differently and exhausted retries escalate rather than repeat (retry patterns for production agents). A prompt that says "retry up to 3 times" is a budget; one that says "retry until it works" is a loop with extra steps.

The status code says which class of action to take. The response body says which specific action. Status codes alone "cannot always convey enough information about errors to be helpful," which is exactly why the IETF published a standard machine-readable error format (RFC 9457 problem details). The format defines five fields: type (a URI identifying the problem kind), title, status, detail, and instance.

The Swagger team's write-up gives the reason this matters for agent clients directly: the new wave of API consumers, AI bots and models, demand precision that ad hoc {"error": "..."} shapes cannot provide, and a standard format lets a client act on the problem rather than string-match on prose (Problem Details, doing API errors well). Here is a response shaped for an agent:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Request validation failed",
  "status": 422,
  "detail": "Two fields are invalid.",
  "instance": "/v1/orders/8f2c",
  "errors": [
    { "detail": "must be a positive integer", "pointer": "#/quantity" },
    { "detail": "must be a valid email address", "pointer": "#/contact_email" }
  ]
}

The type URI is the most valuable field for an agent, because it is stable and short. A prompt can say "if type ends in /validation, fix the pointers" without depending on the title or detail wording, which humans may rewrite. The extension errors array with pointers shows the model exactly which fields to change, which is the difference between one corrective attempt and a rewrite spiral. Frameworks already render this format out of the box: Spring MVC returns ProblemDetail objects with application/problem+json, and the status property on that object sets the HTTP status (Spring's error response docs).

One caution. The standard was previously published as RFC 7807 and later revised as RFC 9457, which obsoletes it (RFC 7807). If your tooling emits or parses the older shape, it is backward compatible, but new APIs should target the current standard.

A handful of status codes are technically valid but actively harmful to an agent client. They cause loops because the model cannot map them to a known action.

Two anti-patterns deserve special mention. Hiding errors inside a 200 response is called out as a serious mistake because it misleads consumers into believing a request succeeded (Zuplo on API error handling). And using a single generic code for every failure strips the response of the information the client needs to act. The rule quoted there is worth adopting verbatim: use the most specific status code that applies.

The 200-with-error pattern is especially dangerous in agent workflows, because the agent's branch logic usually triggers on the status code before it inspects the body. If the request "succeeded" from the transport's point of view, the malformed result gets passed downstream and the real error only surfaces three steps later, in a place where it is much harder to attribute.

Retries only make sense if repeating the request is safe. For reads, this is free. For creates, the agent must send an idempotency key so that a retry after a timeout does not create a second record. One provider documents exactly this contract: an Idempotency-Key header, typically a V4 UUID, guarantees that repeated requests within a defined window return the same response, including error responses, without duplicating the side effect (PostGrid on response codes and retry logic).

Timing matters as much as safety. Exponential backoff with jitter spreads retries so that a fleet of agents hitting a recovering service does not stampede it. The formula is a base delay times a multiplier raised to the attempt number, with randomization applied to the result (PostGrid on backoff and jitter). A worked example with a 30 second base, a factor of 2, and full jitter:

• Attempt 1: 30 seconds calculated, random delay between 0 and 30 seconds.
• Attempt 2: 60 seconds calculated, random delay between 0 and 60.
• Attempt 3: 120 seconds calculated, random delay between 0 and 120.
• Attempt 4: 300 seconds, capped per your policy.

Prefer the server's Retry-After header when it is present, since the server knows more about its recovery time than your backoff formula does. In the Temporal recipe, the Retry-After header is parsed in three forms: retry-after-ms in milliseconds, retry-after in seconds, and retry-after as an HTTP date, with the header overriding the default delay (Temporal's retry recipe).

When does a human get involved? Three conditions should trigger it, and the API should make all three easy to detect:

1. Auth is broken after refresh. A 401 that survives one token refresh is an operator problem, not an agent problem.
2. Permission is genuinely absent. A 403 should page a human or route to a different tool, never to a retry.
3. The retry budget is exhausted. After the third 429 or 503, the agent should stop and report the problem instance URI so an operator can pull the log.

The last point is a design decision the API can support. If the body always carries the instance field with a URI for the specific occurrence, the human who gets paged has a direct handle on the failing request instead of a timestamp and a shrug (RFC 9457).

Before you hand an API to an agent client, walk this list. Each item is something a reviewer can verify in a test.

• Every error path returns a 4xx or 5xx code, never a 200 with an error field.
• Validation failures return 422 with an errors array naming each field.
• Missing or invalid credentials return 401, and insufficient permission returns 403.
• Temporary unavailability returns 503, not 404 or 500.
• 429 and 503 responses include Retry-After in a form the client can parse.
• Create endpoints accept an Idempotency-Key header.
• Error bodies use application/problem+json with a stable type URI per error kind.
• No custom code or joke code is reachable by an agent.
• Your prompt or orchestration code lists every reachable code and has a "stop and report" fallback for anything else.
• The retry budget is capped and recorded per task.

Versioning belongs on this list too. Once an agent's prompt depends on your error type URIs and status semantics, changing them is a breaking change for that client, so document what you change and where you changed it (Speakeasy on versioning and evolution). If you serve many agent clients, a documented, versioned error contract is worth as much as the endpoint itself.

If you are building the agent side and want one endpoint that speaks to text, vision, and embedding models behind a single key, the natural place to start is Quanta Inference, where the same status-code discipline applies to every model call.