iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Settle the API’s public error policy before asking an agent to generate its error mapper. A committed, machine-readable taxonomy gives web, mobile, and partner clients the same stable codes and action-relevant details; the mapper then implements that policy instead of inventing it.
Why define the taxonomy first?
When a service is used by several clients, each needs a consistent answer to two practical questions: what should the user see, and can the request be retried? If those answers exist only in scattered catch blocks, a code-writing agent has to infer the acceptance criteria from implementation details.
The case study describes the risk with the phrase “Six slightly different 4xx answers for the same failure.” Treat that as the author’s framing, not a measured prevalence claim. Its examples include assigning different 4xx statuses to related validation failures, marking a rate-limit response non-retryable based on its name, and copying err.message into a public response. These illustrate decisions an undocumented mapper might make; they do not establish that all agents behave this way.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →As case-study author Dakota Liu puts it, “The problem is not that the agent is careless.” The point is that missing acceptance criteria leave implementation choices open. Freeze the consumer-visible policy first, then delegate code that can be checked against it.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
What belongs in the frozen contract?
Commit a machine-readable list of public error codes, with the same four fields for each code:
- HTTP status: the response status clients should receive.
- Retry semantics: whether the client should treat this error as retryable. Make the policy explicit rather than asking clients to infer it from a code name or status.
- Message key: a stable key that clients can map to appropriate user-facing text. Keep the key distinct from a server-generated explanation or internal exception message.
- Log level: the severity the service should use when recording the event.
The contract is the policy; the mapper is its implementation. Include every field that drives consumer-visible behavior in the committed file so a generation pass has no reason to invent that behavior. The taxonomy should also make clear which codes are stable public identifiers, rather than treating explanatory prose as a substitute.
Rank #2
How this fits HTTP Problem Details
An HTTP status communicates a broad class of outcome, but it may not give an API client enough detail to handle a particular failure. RFC 7807 defines Problem Details for HTTP APIs as a way to pair that high-level status with finer information about the problem. It also says consumers must ignore unrecognized extension members, a useful forward-compatibility rule for clients that encounter new optional details. Read RFC 7807.
Problem descriptions should explain the interface-level failure without exposing stack traces or other implementation internals. 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.” Keep diagnostic context in appropriate internal logs, and avoid problem types or detail that reveal security-sensitive internals.
RFC 9110 provides related general guidance: 4xx indicates that the client seems to have erred, and—except for a HEAD response—the server should send a representation explaining the error situation and whether it is temporary or permanent. That does not mandate this case study’s four contract fields; status, retry semantics, message key, and log level are a design choice for the service. Read RFC 9110.
Keep codes stable and messages safe
Clients need something dependable to branch on. A stable machine-readable code can remain the decision point while explanatory text changes for clarity, localization, or product needs. Parsing prose such as an exception message couples client behavior to wording and can accidentally expose internal details.
Consumers should also tolerate unfamiliar codes and absent optional details. OpenAI’s Agents API documentation gives a concrete platform-specific example: use error.code in application logic, error.message to explain the failure, and error.param to identify a request field when available. It advises handling unknown codes and missing parameters without breaking the error handler. Those are OpenAI API guidance, not requirements imposed by HTTP standards. See the Agents API error guidance.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsGenerate the mapper without changing policy
- Commit the taxonomy. Treat the machine-readable file as the agreed policy input, not as a draft the mapper generator may silently revise.
- Protect its contents in CI. The case study proposes hash-checking the contract so a generation pass cannot quietly change the taxonomy. Use a check that fails when the protected policy changes unexpectedly; handle intentional policy updates through an explicit review process.
- Generate or revise the mapper from the contract. Ask the agent to implement the listed codes and fields. Keep policy decisions out of the generation task unless the contract itself is being deliberately revised.
- Test the mapper against the contract. Check that each listed code maps to its specified status, retry semantics, message key, and log level, and that public output does not leak an internal exception message.
- Exercise unknown and incomplete inputs. Confirm the handler remains usable when a consumer or upstream response presents an unfamiliar code or omits an optional detail.
The case study says its example test runs in under a second. That is an author’s claim about that example, not an independently measured benchmark or a general expectation for contract tests.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When error handlers do more than return HTTP responses
Error categories become especially useful when they guide actions beyond displaying a message. OpenAI Agents SDK documentation describes explicit handlers for supported runtime failures and a tool error formatter for messages sent back to the model. Its invalidFinalOutput handler can return a validated fallback without retrying the model or replaying tool side effects. This is an SDK-specific illustration of why action-relevant semantics matter; it does not mean the case study’s service uses that SDK. See the Agents SDK running-agents guide.
Choose contract-first or infer from existing handlers?
Deriving policy from existing catch blocks can preserve the behavior a service already has, but it also carries forward inconsistencies that may have accumulated between clients or endpoints. Contract-first work makes the desired behavior reviewable before implementation. Neither approach is a universal benchmark: the decision is whether existing behavior is already an intentional, consistent contract or needs explicit reconciliation.
- Choose a stable code over prose when clients must branch reliably.
- Write retry semantics explicitly when clients need to decide whether to try again; do not make them guess from a status or error name.
- Give public clients useful interface-level detail while keeping implementation debugging information internal.
- Use generated code to implement agreed policy, not to decide what the policy should be.
How to adapt this reference implementation
The case study is a pattern to run and adapt in your own repository, not evidence of a measured improvement. Start by identifying every consumer-visible decision currently made by handlers and client integrations. Agree on the taxonomy with the teams responsible for those consumers, record it in the committed file, then make the mapper and its tests depend on that file.
If the contract changes, review the change as a policy update: consider its effect on existing clients, update the taxonomy deliberately, and verify the mapper against the revised entries. The agent can assist with implementation, but the team still owns the compatibility decision.
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.
