An agent that never fails does not exist. APIs time out, tools return garbage, a model invents a step that was never asked for, and a permission check blocks an action halfway through a task. The question that decides whether an agent is usable is not whether it fails, but how it fails. A graceful failure is contained: the agent notices something went wrong, takes a safe recovery path, undoes any half-finished damage, and hands off to a human when it cannot be sure. This guide walks through doing exactly that, step by step.

This is the practical, how-to companion to the conceptual overview in AI agent error handling and rollback. Where that post explains the why, this one is the playbook: how to detect a failure, retry safely, fall back, roll back side effects, escalate, and make every failure visible. It assumes you want a single failure to stay a single failure, not become an incident.

The classes of agent errors

You cannot handle what you have not named. Agent failures fall into a handful of repeatable classes, and each needs a different response. Lumping them together is the most common reason error handling goes wrong: a fix for one class makes another worse. Start by sorting failures into these buckets so you can attach the right recovery to each one.

The five common failure modes

Most agent errors are one of five kinds. Tool and API failures are external calls that error out, time out, or hit a rate limit. Bad outputs are responses that come back malformed, off-schema, or simply wrong. Timeouts are steps that hang past a sane limit. Hallucinated actions are steps the agent invents that were never part of the task. Permission denials are blocked actions the agent had no right to take. Each one wants a different answer, which is the whole point of sorting them.

Here is the distinction that matters most. Some failures are transient: try the same thing in two seconds and it works. Others are permanent: the same call will fail the same way forever. A rate limit is transient. A malformed request or a denied permission is permanent. Retrying a permanent failure just wastes time and money, so the first job of any handler is to ask which kind it is. For a deeper diagnostic angle on misbehaving steps, see how to debug an agent that did the wrong thing.

Detect the failure first

You cannot recover from a failure you did not notice. The hardest agent errors are not the ones that crash loudly; they are the ones that return a plausible but wrong answer and sail straight through. Detection is therefore step one, and it has to be active. Assume every tool result and every model output is guilty until checked, then build the checks that catch the silent failures before they reach the user.

Validate outputs and check against expectations

Two checks catch most silent failures. First, structural validation: does the output match the schema, type, or format you required? A step that should return JSON with three fields either does or does not, and you can verify that automatically. Second, expected-output checks: does the result make sense for the task? A flight-booking step that returns a date in the past, or a total that is negative, has failed even if the format is perfect. These are cheap to write and catch the failures that would otherwise slip through unseen.

In building Gravity's reference agents, the checks that paid off most were the boring ones: assert the field exists, assert the number is in range, assert the action targets the record we expected. They felt almost too simple to bother with. They caught more real failures than any clever model-grading step we tried, because the silent, plausible-looking errors are exactly the ones a strict schema check refuses to let pass.

Retry the right way

A retry is the cheapest recovery there is, and the easiest to get wrong. Retrying blindly turns a brief hiccup into a hammer that pounds a struggling API into the ground, or worse, charges a customer's card twice. The rule is narrow: retry only failures that are transient and safe to repeat. Everything about retries follows from that one sentence. The full pattern lives in AI agent fallback and retry; here is the working version.

Idempotency comes first

Before you retry anything, ask whether running it twice is safe. An idempotent action produces the same result no matter how many times you run it: reading a record, or writing to a known key. A non-idempotent action does damage when repeated: charging a card, sending an email, creating a row. Never blindly retry a non-idempotent action. Either make it idempotent first, usually with a unique request key the downstream system deduplicates on, or do not retry it at all.

Exponential backoff and a retry budget

When a retry is safe, space the attempts out. Exponential backoff waits longer between each try, one second, then two, then four, so a recovering service gets room to breathe instead of a flood. Add a small random jitter so a fleet of agents does not retry in lockstep. Then cap it with a retry budget: a hard limit on attempts, say three, after which the agent stops retrying and moves to a fallback. Without a budget, a retry loop becomes an infinite loop, and the agent hangs forever on a failure that was never going to clear.

Build fallback paths

Retries run out. When they do, a graceful agent does not just throw its hands up; it has somewhere else to go. A fallback is the planned answer to "what do we do when plan A is exhausted". The agents that feel reliable are not the ones that never hit a wall, they are the ones that always have a next move ready. Reliability is rarely about a stronger plan A; it is about having a competent plan B that nobody had to invent under pressure.

Three kinds of fallback

Fallbacks come in three flavours, in rough order of preference. An alternate tool or provider does the same job a different way: if one search API is down, query a second. A degraded result delivers a smaller but still useful answer: return the cached version, or the partial result with a note about what is missing. A safe default is the floor: a known, harmless response when nothing else is available, such as "I could not complete this, here is what I tried". The first preserves quality, the last preserves safety, and a robust agent has all three.

The point of a fallback is that the user gets a sane outcome rather than a stack trace. A degraded answer with an honest note about its limits beats a confident wrong answer every time, and it beats a silent crash by a mile. Decide in advance which fallback applies to which failure, because the worst time to design plan B is the moment plan A is on fire.

Roll back side effects

Some failures happen after the agent has already changed something in the real world. It created the record, then the next step failed. Now you have a half-finished task and a stray side effect sitting in production. Graceful handling means undoing that mess, not leaving it. The conceptual treatment is in AI agent error handling and rollback; the mechanics live in how to roll back an agent action.

Track every side effect so it has an undo

Rollback is only possible if you recorded what to undo. As the agent acts, log each side effect with the information needed to reverse it: the ID of the record it created, the charge it made, the message it sent. When a later step fails, walk that log backward and reverse each effect in turn. Delete the record, refund the charge, send a correction. A task either completes fully or unwinds cleanly, never stranded halfway. This is the same all-or-nothing discipline a database transaction gives you, applied to an agent's actions in the outside world.

Some actions cannot be undone. You cannot un-send an email or un-pay an invoice. For those, rollback is the wrong tool, and the right one is prevention: gate the irreversible action behind a check or a human approval before it runs, so you never need to undo it. Knowing which of your actions are reversible, and which are not, is the single most useful map to draw before you ship.

Escalate to a human

Not every failure should be solved by the agent. When confidence is low or the stakes are high, the safest recovery is to stop and ask a person. A well-placed escalation is not a sign the agent is weak; it is a sign the system knows its limits. The art is putting the approval gate in exactly the right spot: before the risky, irreversible action, not after it. The broader safety framing sits in AI agent guardrails and safety.

Approval gates and confidence thresholds

Use a confidence threshold to decide when to escalate. If the agent's certainty in a step drops below a set bar, or the action exceeds a risk threshold such as a dollar amount, route it to a human for approval before proceeding. The human sees what the agent intends to do and either approves it or corrects it. This keeps the agent fast on the routine majority of cases while putting a person in the loop precisely where a mistake would be expensive. When an escalation turns into a real problem, an agent incident response process takes over.

Fail closed or open

Every error handler faces one fundamental choice: when the agent is unsure, does it stop or does it proceed? Failing closed means halting and doing nothing rather than risk a wrong action. Failing open means continuing with a degraded or default result. Neither is universally correct, and picking the wrong one is its own kind of bug. The choice depends entirely on what a mistake costs.

Match the mode to the stakes

Fail closed when an action is risky, irreversible, or high-value: moving money, sending messages to customers, deleting records, changing access. In those cases, doing nothing and escalating is far better than a confident error. Fail open when the work is low-stakes and read-only: summarising a document, drafting a suggestion, fetching information where a partial answer still helps. The mistake teams make is choosing one mode for the whole agent. The same agent should fail closed on its payment step and fail open on its summary step, because the cost of being wrong is wildly different in each.

Log, alert, and test

A failure you cannot see is one you cannot fix. The final piece of graceful handling is making failures visible: structured logs that capture what failed and why, and alerts that surface the failures worth a human's attention. An agent that recovers silently is good; an agent that recovers and also tells you it had to is far better, because the recovery hides a problem you would still want to solve at the root.

Log the failure path, not just the success path

Log every failure with enough context to reconstruct it later: which step, which input, which error class, and which recovery the agent took. Then alert on the patterns that matter, a rising failure rate, a fallback firing far more often than usual, a retry budget being exhausted repeatedly. These signals tell you a dependency is degrading before it fully breaks. Good logs are also what make debugging tractable when an agent does the wrong thing, the subject of how to debug an agent that did the wrong thing.

Test the failure paths before you ship

Here is the step most teams skip. Your retries, fallbacks, and rollbacks are themselves code, and untested recovery code fails exactly when you need it most. Deliberately break things in testing: make the API return errors, feed the agent malformed output, force a timeout, and confirm the agent recovers the way you designed. This is the heart of AI agent reliability testing, and it belongs in your pre-launch checklist alongside how to test an agent before going live.

This is also where a marketplace changes the picture for buyers. On Gravity, the builder is the one who designs and tests these failure paths, retries, fallbacks, rollbacks, escalation gates, against a quality bar before the agent is ever published. You describe the outcome you want; the safe-failure machinery is already inside the agent. Knowing an agent fails gracefully is precisely what lets you hand it an important task without standing over it.

Frequently asked questions

What does graceful error handling mean for an AI agent?

Graceful error handling means a failed step never silently corrupts the result or cascades into a bigger mess. The agent detects the failure, retries safely if it can, falls back to a backup path if it cannot, rolls back any half-done side effects, and escalates to a human when confidence is low.

When should an agent retry versus give up?

Retry only transient, idempotent failures such as timeouts, rate limits, and temporary network errors, using exponential backoff and a fixed retry budget. Do not retry a permission denial, a malformed request, or a bad output, because the same call will fail the same way. Those need a fallback or a human, not another attempt.

What is the difference between failing closed and failing open?

Failing closed means the agent stops and does nothing when it is unsure, which is safest for actions that move money, send messages, or change records. Failing open means it proceeds with a degraded or default result, which suits low-stakes, read-only work. The right choice depends on how costly a wrong action is.

How do you roll back an agent action that already ran?

Track every side effect the agent causes so each one has a defined undo: delete the created record, refund the charge, send a correction. Where an action cannot be undone, gate it behind a human approval before it runs. Recording effects as you go is what makes a clean rollback possible later.

Do buyers configure error handling on a marketplace agent?

No. On a marketplace like Gravity, the builder bakes retries, fallbacks, rollbacks, and escalation rules into the agent and tests them to a quality bar. You describe the outcome you want. Knowing an agent fails safely is why you can trust it to run an important task without watching every step.

Three takeaways before you close this tab

Sources