A tool call fails. The agent tries again. The same error returns. After several attempts, the workflow is still stuck—and nobody knows whether the last action completed.
AI agent error handling is the application logic that identifies a failure, preserves evidence and chooses a permitted next step. That step may be a bounded retry, an input correction, a supported fallback, a stop or a handoff. Choosing it requires more information than an exception message.
Start by checking whether the operation can change a business system and whether its outcome is known. A missing response after a write needs different handling from a read that clearly failed before returning data.
Ask three questions before choosing a recovery path
- What failed? Separate model-provider errors, tool execution errors, invalid arguments, authorization denials and application-rule failures.
- What happened already? Establish whether the downstream service rejected the action, confirmed it, is still processing it or left the outcome uncertain.
- What may happen next? Apply the workflow’s permissions, retry budget, deadline and escalation rules before the agent attempts another action.
This guide proposes a framework-independent decision method. Microsoft’s exception-handling documentation illustrates middleware that catches failures and returns fallback responses. A production workflow also needs to decide what those failures mean for business state.
Use a failure decision table instead of one retry rule
| Failure class | Evidence to inspect | Candidate next action |
|---|---|---|
| Temporary dependency failure | Provider status, retry guidance, attempt history and whether the operation is repeat-safe | Retry within the documented policy and remaining workflow budget |
| Invalid tool arguments | Schema error, submitted values and required fields | Correct supported fields or request missing information; validate again |
| Authorization denied | Authenticated identity, resource and current grants | Stop the denied action and route through the approved access process |
| Business-rule conflict | Current record version and required state transition | Refresh permitted state; obtain a new decision if the proposed action changes |
| Unknown write outcome | Operation reference, target-system receipt and reconciliation status | Check the existing operation or escalate; do not assume nothing happened |
| Unsupported or unreliable model output | Validation results and available source evidence | Reject the output; use an approved alternative or review path |
| Retry budget exhausted | Attempts, elapsed time, outstanding effects and failure summary | Stop automatic attempts and hand over with an explicit unresolved status |
This is a proposed design table, not a provider-wide error-code mapping. Read each integration’s actual response semantics. A status code or a timeout by itself may not reveal whether a downstream write committed.
Put a limit on attempts and on elapsed time
A retry policy should identify eligible failures, maximum attempts, delay behavior and the total deadline for the business task. Respect documented provider retry instructions. Count retries across the adapter, SDK, queue worker and orchestration layer so separate policies do not multiply attempts unnoticed.
LangChain’s fault-tolerance guide documents retries with backoff, node timeouts and handlers after retry exhaustion. These controls supply execution mechanisms; the team still needs to decide which failures are eligible and what the exhausted path should do.
Use delays and jitter where appropriate for temporary dependency failures. Consider a circuit breaker when repeated failures indicate that calls should pause for a recovery period. Define how the service resumes and what happens to waiting work. Do not let a model invent delay or retry limits during a conversation.
A timeout bounds waiting in one part of the application. It does not automatically undo an external action or prove that a remote service stopped. Track execution outcome separately from the caller’s waiting deadline.
Keep error messages useful without making them instructions to bypass controls
Give the agent a structured, limited account of the error: the category, affected operation, permitted correction and whether human input is required. Keep secrets, raw stack traces and unnecessary customer data out of the message.
For example, a missing required region may be repairable from an already verified address. A denied permission is not permission to try another identity. An ambiguous amount should not be filled with a plausible guess simply because the schema requires a number.
Validate a corrected request through the same application checks as the original. If the correction changes the approved business operation, apply the approval process again.
Distinguish a fallback answer from a fallback action
A fallback can keep a user informed when a dependency is unavailable. It should state what remains unresolved. An alternative model or retrieval path must still meet the task’s evidence, data-access and action requirements.
A cached read may be acceptable for a task that tolerates older information, provided the age is visible. It may be unsuitable for confirming a current balance or permission. Likewise, a cheaper model is not an appropriate recovery path if it lacks the required capability.
For multi-step workflows, assess whether already completed steps need compensation. A cancellation or compensating action is itself a business action with its own permissions and possible failures. Preserve unresolved compensation work instead of claiming that a rollback succeeded without confirmation.
Handle uncertain writes through the existing operation record
AWS’s guide to idempotent APIs explains how retries can create unwanted side effects when a caller does not know whether a previous request succeeded. It describes caller-provided request identifiers as part of an idempotent API contract.
For an agent workflow, route this failure class to the integration’s existing operation record and reconciliation procedure. LuMay’s AI agent idempotency guide covers operation identity, concurrency and duplicate suppression in detail. Keep that implementation outside a generic retry loop.
Worked example: a support workflow loses a dependency
Hypothetical example: an internal support agent looks up an employee’s device and prepares a replacement request. The workflow has three different failures:
| Observed failure | Recovery decision | User-visible result |
|---|---|---|
| Inventory read is temporarily unavailable | Use bounded retries within the read policy; escalate if the dependency remains unavailable | Device lookup is unavailable; no replacement has been submitted |
| Replacement request is denied by the access service | Stop the write and route to the authorized support role | An authorized reviewer must handle the request |
| Submission response disappears after the write was sent | Reconcile the existing operation reference before deciding whether any repeat is permitted | Submission status is being checked; outcome remains unresolved |
The same “try again” response would be wrong for at least some of these states. The recovery path should communicate what is known and hand over enough evidence for someone to continue.
Make escalation an owned workflow
A handoff needs a destination and evidence of acceptance. Record the failed step, failure category, operation reference, attempts, last confirmed state, outstanding effects, permitted next steps and relevant trace references. Include only information the receiving role is authorized to see.
Keep the case pending until an owner accepts it or the queue’s service rule resolves the assignment. If no operator is available, tell the user that the work is unresolved and provide the organization’s defined next step. An emitted alert alone does not establish that a person took ownership.
Test the decision branches before release
Inject a temporary outage, an invalid argument, a permission denial, a stale record and a timeout after submission in an authorized test environment. Confirm that each case selects the intended branch, stays within its attempt budget and reports an accurate status.
Measure exhausted runs, unresolved operations and accepted escalations separately from eventual success. Use LuMay’s tool contract testing guide to validate response meanings and the agent incident-response runbook when failures require broader containment.
Questions engineering teams ask about error handling
Q1: Should an agent retry every server error?
A: No. Check the service’s documented behavior, the operation’s side effects and the remaining budget. A response category alone does not establish that repeating a write is appropriate.
Q2: Is a timeout the same as a failed action?
A: No. It establishes that a response or progress deadline was missed. The remote action may still be running or may already have completed.
Q3: What should happen after a rate-limit response?
A: Follow the provider’s retry guidance within the task deadline. Reduce or queue demand where supported rather than increasing parallel attempts.
Q4: Can the model repair malformed tool arguments?
A: It can propose a correction when the needed information exists. The application must validate the corrected request and recheck its authority before execution.
Q5: What should happen after a permission denial?
A: Stop the denied action and use the approved review or access process. Do not silently switch accounts, broaden permissions or reinterpret the denial as a transient outage.
Q6: What if both the SDK and orchestrator retry?
A: Inventory the retry layers and assign an overall budget. Log attempts at each layer so the team can see the total calls generated by one business request.
Q7: When does a circuit breaker help?
A: It can pause calls to a repeatedly failing dependency. Define the failure signal, waiting behavior and recovery probe; it does not replace operation reconciliation or authorization checks.
Q8: Can an agent claim success after returning a fallback message?
A: Only when trusted evidence confirms the requested outcome. A friendly explanation or cached answer is not a receipt for an external action.
Q9: How should errors during streaming be handled?
A: Mark the response as incomplete and retain the last confirmed workflow state. Do not execute partially received action fields or imply that an unfinished response completed the task.
Q10: What if the compensation step also fails?
A: Record which effects remain and route them to an accountable owner. A failed cancellation or reversal leaves unresolved work; it should not be presented as a completed rollback.
Q11: What belongs in a human handoff?
A: Include the failure category, last confirmed state, operation reference, attempt history and permitted next steps. Limit the context to what the receiving role may access.
Q12: How can a team detect silent failures?
A: Check business outcomes as well as exceptions. An apparently successful API response can still lack the required record or workflow state. Use contract assertions and investigate unsupported success messages.
Define the next action for one failure-prone workflow
Choose one workflow and write down what happens after each failure class. Name the owner of exhausted or uncertain work, then test that the handoff actually reaches that owner.
Bring a solution you want to productionize and one failure path that needs a clear owner. LuMay’s AI engineering services provide a starting point for discussing the integration and operational requirements.





