On this page
The short answer
Classify a tool error by what the application knows and what action remains safe. Invalid arguments, denied access, transient capacity, missing resources, and uncertain commits need different responses. Evaluate whether the agent chooses a permitted recovery and preserves evidence, rather than scoring every eventual answer as a recovered task.
What to take away
- Return structured error categories without sensitive details.
- Keep uncertain commits separate from confirmed failures.
- Test useful recovery and legitimate stopping.
Sources checked . Research synthesis and Rubrex recommendations. Examples and local experiments are labeled; they are not client results.
Define errors in the adapter contract
LiteLLM’s architecture separates provider requests, retries, and fallback handling. Rubrex recommends giving business-tool adapters an equally explicit error contract. An undifferentiated failure string forces the model to guess whether it should fix an argument, wait, ask the user, or stop.
Use an illustrative document-export tool with categories for invalid format, access denied, missing source version, temporary queue capacity, and export completion unknown. Include a stable code, safe explanation, retry eligibility, and operation reference where appropriate. Exclude credentials and raw internal traces from the model-visible message.
Evidence: LiteLLM: Life of a Request [1]
Pair each error with a different expected behavior
Return an invalid-format error when the user requested a supported alternative; the agent can correct that argument. Return access denied for a private source; it must not retry using a different identity. A temporary capacity error can permit a bounded wait only if the task deadline allows it.
For missing source versions, ask whether a newer version is acceptable rather than silently changing evidence. For unknown export completion, inspect the operation receipt before creating another export. These cases deliberately share the same top-level task so that the evaluated difference is error interpretation, not unrelated prompt difficulty.
Inspect recovery paths and unresolved outcomes
Record the error category, attempted next action, total attempts, final state, and any user clarification. Include a misleading natural-language error body that recommends a forbidden endpoint while its structured category remains access denied. The adapter’s trusted policy should govern recovery rather than arbitrary tool text.
Report category-specific success, false recovery, and unnecessary stopping. A single recovered percentage can hide authorization bypasses under many easy format corrections. Include a normal export control and a permanent failure with no safe alternative, for which an honest blocked response is the successful task behavior.
| Case | Evidence to retain | Acceptance condition |
|---|---|---|
| Invalid format | Error code and corrected argument | Supported correction only |
| Access denied | Principal and next action | No credential switching |
| Unknown completion | Operation lookup | Reconcile before new export |
Keep the taxonomy small enough to operate
Accept the first version when every exposed category has an owner, an observable expected response, and a retained failure case. Add categories when they lead to different recovery decisions, not merely because exception class names differ. Merge categories that require the same action and evidence.
Review unknown errors separately and decide whether to add a safe classification or preserve a controlled stop. Update the fixture when the upstream API changes its failure contract. The goal is a repeatable decision at a failed step, not a catalog of every possible network or model exception.
Limits of the evidence
The export service and taxonomy are illustrative recommendations. No tool runtime was exercised. Error categories and retry eligibility must be reconciled with the actual upstream contract; a generated explanation cannot establish whether a write committed.
Common questions
Should raw exceptions reach the model?
Expose only the structured, safe information needed for recovery; retain restricted diagnostics separately.
Is stopping always a failure?
No. A controlled stop is correct when no authorized recovery fits the task contract.
Sources & further reading
Primary sources behind this briefing. A source’s findings apply to its own study conditions; publication on arXiv does not establish peer review.
- LiteLLM: Life of a Request LiteLLM · Living reference · Maintained documentationReviewed: documented gateway request lifecycle and retry-versus-fallback distinction. Accessed October 16, 2026.
Questions or corrections? Write to Rubrex. Read our editorial approach.