Teaching a Tool to Return a Hint With Every Error

A stable machine code. A short string, specific to your application, that never changes meaning once published. trip_not_possible is the canonical example of a code layered on top of a generic 400, precisely so that client code can branch on it (if (error.code === 'trip_not_possible')) while the message stays free to be reworded (Speakeasy). Treat the code as API surface: renaming it is a breaking change, and your contract suite should catch it. Compare that to bare exit codes in a CLI, where the well-known values (1 for general errors, 126 for "cannot execute", 127 for "command not found") collide with user-defined uses until nobody can tell a "command not found" from an application policy, which is exactly the trap the Advanced Bash Scripting Guide warns about (TLDP Appendix E).

A short message. One sentence, plain language, describing what happened to this request. Not a stack trace, not a paragraph of remediation. The message is for the log line and, in some cases, for a human reading the transcript afterwards. Keep it under roughly 120 characters and never put a variable-length array of details in it.

A next-step hint. A structured object, not prose, naming the action and its parameter. The hint is the field that makes the agent's decision cheap. It should carry an action from a closed set (retry, fix, escalate, wait), a target (which field, which header, which command, which team), and, where relevant, a machine-readable timing value.

Here is a payload shape that carries all three, on top of RFC 9457:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Request validation failed",
  "status": 422,
  "instance": "/orders/req_8f21",
  "code": "order_quantity_invalid",
  "message": "quantity must be a positive integer",
  "retryable": false,
  "hint": {
    "action": "fix",
    "target": "body.quantity",
    "detail": "Send an integer of 1 or more."
  }
}

Note what each field does. status and type categorize. code identifies. message explains. retryable is a boolean the agent can check before writing any retry loop. hint.action and hint.target tell it where to apply the fix. An agent that received only the 422 and the message would probably still get there, but it would spend a model call and a guess. An agent that receives the hint does not.

The three actions map to three questions, and the payload should answer all three without the agent inferring anything.

Two rules make this table work in practice.

First, retryable: false must be honest and obvious. A 400 means the client sent a bad request and must change something before retrying; a 500 means the server failed on a valid request and a retry is usually reasonable (Zuplo). If you mark an error retryable, mean it. If a validation error is marked retryable, agents will loop on it and burn your rate limit.

Second, escalation needs a destination. "Escalate" with no owner is the same as having no hint at all. Name the team, the runbook, or the support queue, and include a correlation id so the human can find the request. The instance field in RFC 9457 exists for exactly this log correlation (Zuplo), so reuse it in the hint rather than inventing a second id.

Validation failure. Status 422, code: "order_quantity_invalid", retryable: false, hint {action: "fix", target: "body.quantity"}. RFC 9457 supports an errors array for reporting several validation problems at once, each with a detail and a pointer (Zuplo). Put the field path in the pointer and let the agent patch each one in a single pass instead of one round trip per field.

Rate limit. Status 429, code: "rate_limit_exceeded", retryable: true, hint {action: "retry", after_ms: 2000, max_attempts: 3}, and always send Retry-After on the 429 (Zuplo). Without a timing value the agent invents one; with it, the agent waits exactly as long as you told it. This is the cheapest hint you will ever add and the one with the largest effect on agent behavior.

Auth failure. Split this into two codes, because the fix differs. token_expired (401) gets {action: "retry", target: "Authorization", detail: "Refresh the token and resend."}. insufficient_scope (403) gets {action: "escalate", owner: "platform-access", detail: "Request the orders.write scope."}. The 401 is a fix the client can automate; the 403 is a policy decision a person has to make. Collapsing both into one auth_failed code guarantees the agent does the wrong thing half the time.

Upstream failure. Status 502 or 504, code: "upstream_timeout", retryable: true, hint {action: "retry", after_ms: 500, max_attempts: 2}, plus a fallback hint for the exhausted case: {action: "escalate", owner: "payments-oncall", ticket_ref: "PAY-114"}. Agents do not know your retry budget unless you state it. State it in max_attempts, and when that budget is spent, the answer to "what now" should already be in the last payload.

One important constraint: never put secrets in a hint. Do not echo the submitted API key in an auth error, and do not name internal hostnames in an upstream error. The Microsoft guidance on error handling is direct about this: generic messages that do not reveal internal details reduce the risk of leaking database structure, keys or credentials (Microsoft Tech Community).

An error is a machine-readable response, so treat it like one. A CLI design guide that has been through several iterations makes the point bluntly: JSON goes to stdout, everything else to stderr, and stdout is your API contract (Writing CLI Tools That AI Agents Actually Want to Use). The same applies to error bodies. Keep the JSON flat and consistent: if after_ms is a number in one error, do not make it a string like "2 seconds" in another. Inconsistent types are a silent failure mode in agent workflows, and silent failures are worse than loud ones.

That guide also makes the case for documented, specific exit codes over a catch-all 1, because an agent that gets a distinct code can decide to skip a step and move on, while an agent that gets 1 for everything has to parse stderr and will sometimes get it wrong (Dev.to). Your error code field is that exit code for HTTP. Give it the same care.

A CLI that serves both audiences shows how the hint can be layered without duplicating logic. The OpenStatus team rewrote their ConnectRPC error codes into actionable guidance: a 404 tells you to run list, an auth failure tells you to verify with whoami, and a missing flag error lists exactly which flags to provide (OpenStatus engineering blog). That is a hint in prose form. Structured hints are the same idea with the prose replaced by fields the agent can branch on directly.

This is the part that keeps the design honest. A contract test is not a functional test of the provider: it exists to catch bugs in how the consumer builds requests or handles responses, and misunderstandings about how the provider will respond (Pact consumer tests). Error payloads are exactly such a response shape, so they belong in the contract suite alongside the happy-path cases.

The golden rule for contract assertions: only assert on things that will affect the consumer if they change (Pact). For an agent consumer, that means all five properties below, and nothing about internal error classes, log formats or stack traces.

Two further rules matter for agents specifically.

Assert on the wire, not on the object. A unit test on your error-constructor function proves the function works. It says nothing about JSON serialization, the header set, the status mapping or protocol handling. Run the failure scenarios through a real client against a test server, the way ASP.NET Core integration tests submit requests to the app and assert the actual response against an expected one (Microsoft Learn). The layered point is that business logic, contract shape and end-to-end transport are different questions; an error payload can be wrong at any layer.

Assert in both directions. The positive case (a bad request produces this exact code and hint) and the negative case (a good request never produces this code). The negative assertion is what catches an error being returned for the wrong reason. A Go CLI integration testing approach that runs the compiled binary and compares output against golden files is a clean fit: the tests need to change only if the behavior of the program changes (Writing integration tests for a Go CLI application). Store one golden file per failure scenario and diff the whole body.

Finally, keep the hints within the retry budget you actually enforce. If the hint says max_attempts: 3, your rate limiter or backoff should not be counting to 5. A test that simulates three retries and then asserts a 429 with an escalate hint is cheap and catches exactly the mismatch that turns an agent loop into an incident.

The hardest part of error contract testing is not the assertions. It is ensuring every declared error has a test at all. Coding agents are literal and will implement what you specify, but they will not invent the failure cases you left out. A workflow that hands out gates has the same lesson: spend the time on requirements and acceptance criteria up front, because agents are extremely literal and vague instructions yield code that technically matches what you said but misses what you meant (How I Validate Quality When AI Agents Write My Code).

The practical fix is a definition of done that requires a recorded run: the test command ran after the agent's last edit and exited 0, and the pull request includes the log of each command and its exit code (SpecStory). Apply the same rule to errors. A handler that can return code: "order_quantity_invalid" is not done until a named test asserts the full payload on the wire. If you generate the code list from a single schema constant, the contract suite can iterate over every code and fail when one has no test, which closes the gap at the schema level rather than in a checklist.

For teams running agents against many models and tools, the failure taxonomy becomes infrastructure. A single error shape across your own services helps, but the tools the agent calls may come from anywhere, so a retry policy keyed on retryable and after_ms is reusable across every model and endpoint you connect. That is the role Quanta Inference plays: text, image, video, audio and embedding models through one API key, OpenAI-compatible, so the same error-handling loop works whether the call goes to a chat model or an embedding model.