Errors have a new reader, and it isn't you
By Aditya Perswal
Who reads your API errors? For fifty years the answer was a person. The system threw, a human read the failure, the human fixed the call. Every error message assumes a human is reading it. It gives a label, a request id, and a link to the docs, which is fine for someone with a browser and twenty minutes.
A person isn't who's reading anymore. Today it's a coding agent working unattended in the background, like Claude Code on an overnight job or a Codex run seventeen steps into a pipeline. The agent reads the error in its retry loop and decides what to do next. And the agent can only act on what you wrote in that error.
What a bare label does to an agent
An agent that gets "Invalid request" resends the same body and gets another 400. It guesses at a different body and gets another 400. Then the run stops and a person has to look at it, because the error gave the agent nothing to act on.
The error is the fix
So we write every error as the fix. Each one says what broke, which field broke it, and the exact change to make, with an example value the agent can paste. An agent told to send a valid duration has to guess. An agent shown "start_within": "00h-00m-30s" doesn't. There's also a machine-readable code your handler can branch on, the name of the field that failed, and a doc_url for the person who looks later.
In the shape you called
The error arrives in the shape of the endpoint you called. Call the OpenAI endpoint, get an OpenAI-shaped error. Anthropic, Google, and Bedrock work the same way. Your SDK already parses it and your retry logic already reads it.
An agent that gets the fix edits its own request and finishes the run. The retry loop ends at the first error, the agent spends fewer tokens, and no person has to look at it.