Design API errors an agent can act on

#ai #api #webdev #tutorial

A human reads "Something went wrong" and tries again later. An agent reads it and does the same thing, except it does it four hundred times a minute with someone else's money. Most API error design is written for the human. Agents are now the caller that stresses every ambiguity you left in, and they cannot squint at your error page and guess.

This post uses a fictional paid data API. The failure modes are from real integrations.

The three questions every error must answer

When a call fails, an agent needs to decide one thing: what to do next. Every useful error answers three questions in fields, not prose:

Can I fix this by changing my call? (bad input, wrong entity, missing field)
Can I fix this by waiting? (rate limit, source timeout, maintenance)
Is this unfixable from my side? (not covered, not found, upstream dead)

If your 400 and your 503 both say "error", you have forced the agent to treat a typo and an outage as the same event. It will retry the typo and abandon the outage, which is exactly backwards.

Structure beats status codes

HTTP status codes are a good first byte and a bad complete answer. They were designed for a handful of cases; your API has dozens. Put the decision in the body:

{
  "error": {
    "code": "entity_not_in_coverage",
    "retryable": false,
    "retryAfter": null,
    "detail": "No registry in our coverage can serve company X in country Y.",
    "docs": "https://api.example.com/errors/entity_not_in_coverage",
    "covered": ["GB", "FR", "NO"]
  }
}

Three fields do the heavy lifting:

code is an enum from a published list. Agents switch on it. The moment you change the string, every client breaks, so version it like your API.
retryable is a boolean promise. An agent that respects it never burns a retry on a permanent failure, and never abandons a transient one.
Everything the caller needs to self-serve is inline: the coverage list, the expected format, the current quota. A round-trip to your docs site is a round-trip too many.

Retries deserve their own contract

Retryable errors need two more fields: retryAfter (seconds, not a timestamp - clocks disagree) and an idempotency story for the retried call. If a retry can double-charge or double-create, say so and give the caller a key to prevent it. "Safe to retry with the same idempotency key" is a complete sentence that saves your support inbox.

Rate limits are the most common retryable error and the most commonly undocumented one. The headers exist (Retry-After, RateLimit-*); use them, and mirror the same values in the body, because many agent HTTP stacks surface the body more easily than headers.

Say no with the same care as yes

The most valuable errors are the honest negatives: not covered, not found, cannot verify. They are product answers, not failures, and they should be as designed as your happy path: structured, stable, and carrying whatever the caller needs to route around you. An agent that gets a clean "no, and here is the boundary" today comes back tomorrow. One that gets a 500 with a stack trace files you under "unreliable" and never returns.

A 60-second audit of your error surface

Trigger each of these on your own API and read what comes back:

malformed input - does the error name the field and the expected shape?
entity outside coverage - is the no machine-readable, with the boundary included?
rate limit - is there a retryAfter in seconds and a retry contract?
upstream source down - is it distinguishable from a permanent failure?

Four errors. If any of them returns prose where a decision should be, an agent somewhere is guessing - and guessing wrong, at scale, with your name on the integration.

This article was generated by an AI system.

DEV Community