Settle the public error contract before asking an AI coding agent to write or revise an error mapper. For a service used by a web app, a mobile app, and a partner integration, a committed list of stable error codes and their consumer-visible behavior gives the mapper clear acceptance criteria—and keeps clients from receiving inconsistent answers about status, retryability, or what message to show.
This case study is a reference implementation to adapt, not evidence of a measured industry-wide effect. Its central lesson is that the agent should implement policy that the team has already decided, rather than infer policy from scattered catch blocks.
As an Amazon Associate I earn from qualifying purchases.
Why freeze the taxonomy before generating the mapper?
A mapper translates internal failures into responses clients can act on. If its policy is implicit in existing catch blocks, a code-generation pass has to guess what counts as correct. The case study illustrates the risk with examples such as sibling validation failures receiving different 4xx statuses, a rate-limit response being marked non-retryable based on its name, or an internal err.message being sent directly in a response.
These are examples of inconsistent decisions in the case study, not measured rates or proof that coding agents generally behave this way. As Dakota Liu puts it, “The problem is not that the agent is careless.” The point is that missing acceptance criteria leave an implementation task under-specified.
#1 Best Overall
Freeze the decisions clients depend on first. Then make the mapper responsible for applying them, and test that implementation against the contract.
What belongs in the error contract?
For each public error code, the case study proposes a committed, machine-readable record containing four fields:
- HTTP status: the status returned for that error.
- Retry semantics: whether a client should retry, expressed explicitly rather than inferred from a code name.
- Message key: a stable identifier that lets clients select an appropriate user-facing message without treating arbitrary prose as a protocol.
- Log level: the intended severity for recording the event internally.
The contract is the policy source; the mapper is its downstream implementation. Include every consumer-visible field in the frozen file, so the mapper does not have to invent behavior. A human-readable explanation may be useful, but keep it separate from stable identifiers and from implementation debugging details.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
The case study also recommends hash-checking the contract in continuous integration. That makes an unreviewed change to the policy file visible rather than allowing a generation pass to alter the taxonomy quietly. The hash check protects the contract from unnoticed edits; it does not, on its own, prove that the mapper conforms to it.
How does this fit HTTP Problem Details?
HTTP status alone may not tell an API client enough to handle a failure. RFC 7807 defines Problem Details so an API can pair the broad error class conveyed by the status with more specific information about the problem. It also says consumers must ignore extension members they do not recognize, a useful rule for forward-compatible clients. Read RFC 7807 at the RFC Editor.
Problem Details is not a license to expose internal exceptions. RFC 7807 states: “Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface itself.” Public descriptions should help a client understand the interface-level problem without disclosing stack traces or other sensitive implementation information.
Rank #3
RFC 9110 gives general guidance for client-error responses: the 4xx class indicates that the client seems to have erred, and, except for a response to HEAD, a server should send a representation explaining the error situation and whether it is temporary or permanent. This supports useful error responses, but it does not require the case study’s exact four fields or dictate its retry policy. Read RFC 9110 at the RFC Editor.
Keep codes, messages, and optional details distinct
Stable machine-readable codes are safer for application logic than parsing explanatory prose. Messages can change for clarity, localization, or product needs; clients that branch on message text can break when wording changes. Likewise, a public description should not simply pass through an internal exception message.
OpenAI’s Agents API documentation provides a platform-specific example of structured errors: it advises using error.code in application logic, error.message to explain the failure, and error.param to identify a request field when available. It also advises handlers to tolerate unknown codes and missing parameters. This is guidance for that API, not a requirement imposed by HTTP standards or a statement that the case study uses OpenAI’s API. See OpenAI’s Agents API error guidance.
Rank #4
Apply the same resilience principle to your own consumers: preserve stable known-code behavior, ignore unrecognized extension details, and avoid making optional fields prerequisites for handling an error.
Make retry decisions explicit
A status or code name alone may not express the action a client should take. The case study’s rate-limit example shows why a mapper should not decide retryability by guessing from a label. Put the intended retry semantics in the contract, then have clients and the mapper use that decision consistently.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallAction-relevant categories matter beyond HTTP APIs. The OpenAI Agents SDK documents explicit handlers for supported runtime errors and a tool-error formatter for messages returned to the model. Its invalidFinalOutput handler can return a validated fallback without retrying the model or replaying tool side effects. This illustrates why error categories can encode meaningful recovery behavior; it does not mean the case study uses that SDK. See the Agents SDK running-agents documentation.
Generate and verify the mapper
Once the team has settled the contract, the agent’s job becomes more bounded: implement the mapping without changing the policy. Treat the following as a repository workflow, adapting the checks to your language, generator, and CI setup:
- Commit the policy file. Record each public code with its status, retry semantics, message key, and log level. Review changes as policy changes, not incidental generated output.
- Generate or revise the mapper from that file. Give the agent the contract as the source of truth and ask it to implement each declared mapping without adding or inferring consumer-visible behavior.
- Check the contract’s integrity in CI. Compare its expected hash with the committed value so an unnoticed edit is detected. A deliberate policy change should be reviewed and reflected in the expected hash through the normal change process.
- Test the mapper against the contract. Verify that every declared code produces the specified status and retry semantics, selects the declared message key, and uses the intended log level. Also exercise unknown codes and absent optional details so error handling does not itself fail.
- Review public output separately from internal logs. Confirm that clients receive useful interface-level information, while internal diagnostics remain available through appropriate logging rather than being exposed as raw exception text.
The case study says its example test runs in under a second. That is an author claim about the example, not an independently measured benchmark or a guarantee for another repository.
Choosing contract-first generation or existing catch-block behavior
Deriving policy from existing catch blocks can be convenient when a service already has a well-maintained, consistent contract. But where behavior is scattered or undocumented, encoding it as the source of truth risks preserving inconsistencies and asking the agent to infer acceptance criteria. A contract-first workflow is useful when multiple clients need the same stable answers and the team can review policy explicitly.
Free tools Windows power users keep installed
One-click scans. No signup required.
The design choice is not a universal performance contest. It is a question of where policy should live, how clients should interpret it, and how changes should be reviewed. Stable codes, explicit retry semantics, and a deliberate separation between public detail and internal debugging information make those decisions easier to inspect and test.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
