AI Tool Errors: Which Failures Need a Human Decision

An AI tool error should send work to the person or process that can resolve it. A malformed date may need a correction; a refused permission may need an owner’s decision. Treating both as “try again” wastes time and can turn a recoverable problem into an unauthorized action.

This reference separates sixteen response cases into four routes: repair, inspect, decide and wait. The routes are our operating recommendations. A response code provides evidence about what happened; the task’s scope and the destination’s actual state determine what the agent may do next.

Start with the most specific trustworthy response available. The group names describe the next kind of work, not severity. A case can move from inspect to decide once the missing evidence is recovered. Apply the table only within the permissions and budget already granted.

RFC 9110 distinguishes access refusal, resource-state conflict and failed preconditions. A 403 response should not be automatically repeated with the same credentials. A 409 can require resolving a state conflict. Those meanings do not establish that every occurrence needs a human.

RFC 9457 provides a structured format for API problem details. Its type identifier and defined extensions are more suitable for machine routing than parsing the human-readable detail sentence. Our four routes are a synthesis layered above those protocol concepts.

An application may use a different error format or put domain failures inside an otherwise successful response. Inspect its documented contract. Do not infer the meaning of a vendor-specific code merely because its wording resembles an HTTP status.

Imagine an illustrative agent exporting a set of approved documents. The connection drops after the destination starts processing. The agent has evidence of a communication failure, but no evidence that the export failed. Its next useful action is a read-only lookup of the job or destination, not another export request.

Save the operation identifier, attempted target, last confirmed state and any completed item identifiers. If no lookup is possible, report the uncertainty plainly: the request may have completed, and repeating it may create another copy. The owner can then choose whether waiting or reconciliation is appropriate.

This is a different problem from choosing a backoff interval. Our long-running tool-call guide covers keeping track of an ongoing call; this table determines what its response means for the task.

A useful escalation names the blocked action, the relevant constraint and the available choices. “The approved spending ceiling is reached; the remaining files are untouched. Reduce the scope or approve a revised ceiling” is actionable. “The tool failed” leaves the owner to reconstruct the whole run.

Include evidence without copying secrets or a full diagnostic dump into the conversation. Preserve a reference to the restricted log if someone needs deeper investigation. The owner needs the reason and consequences, not every implementation detail.

Do not make the owner approve corrections already covered by the request. Reformatting an unambiguous date is ordinary execution. Choosing which of two clients the date belongs to changes the target. The distinction follows the ask-versus-guess decision rubric.

Choose a workflow with a clear destination and list its actual failure responses. Map each to the table, then record the evidence that permits recovery. Where the mapping is unknown, leave it unresolved until the tool contract or a controlled test supplies the missing information.

Give every recovery route an end condition: verified completion, a preserved partial result, an explicit decision request or a documented stop. “Keep trying” has no useful completion boundary. The background-work cancellation guide explains what to check when the run must end.