When an AI agent's tool call fails, the first job is to decide what kind of failure it is, because each kind needs a different recovery. Retry transient errors with backoff and a cap on attempts. Stop on quota and authentication errors and report what finished. When the tool's own environment could be the cause, check again from somewhere else before believing the result. When a call succeeded too early, wait on a condition that only the new state can meet. And make every write idempotent, so that a repeat or a changed input cannot leave duplicates behind. We sorted the seven tool failures our own agents hit between 14 and 17 November 2026 into these five kinds, and the recoveries below are the ones that worked.
The seven failures
Our agents are Claude Code sessions and a scheduled writing run that work on this website: drafting posts, checking them, running experiments, and releasing to the live site when the owner says so.
| # | What happened | Kind |
|---|---|---|
| 1 | A model API account hit its usage limit part-way through an experiment: 42 of 104 planned calls finished | Hard limit |
| 2 | A link check passed on a laptop in India and failed in CI, because the CI machines could not reach an Indian government site | Environment |
| 3 | A search-engine notification went out while the old build was still serving | Wrong moment |
| 4 | A TLS check reported that our site refused old protocol versions; the refusal came from the checking tool | Environment |
| 5 | A link check to a standards site timed out at 8 seconds, then answered in under a second on the next run | Transient |
| 6 | Moving two posts to an earlier date would have left the old files behind, so each post would have appeared twice | Repeat not safe |
| 7 | After the site moved to a new branch, the scheduled writer's own instructions still pointed at the retired one | Wrong target |
Two of the seven, numbers 2 and 4, reported a failure that was real but sat in a different place from where it appeared. Those were the costly ones, because the first reading was confidently wrong.
Transient failures: retry, with a cap
A timeout or a "try again later" response usually clears on its own. Microsoft's retry pattern guidance sets out the three choices: cancel when the fault is unlikely to clear, retry at once for a rare one-off fault, or retry after a delay that grows with each attempt. HTTP has a status for exactly this case, 429 "Too Many Requests", defined in RFC 6585, which may carry a Retry-After header telling the client how long to wait.
Our link check (number 5) timed out once against a site that answered in well under a second a minute later. One re-run was the right recovery. Three rules keep retries from becoming the problem:
- Cap the attempts and the total time, and stop with a clear error when the cap is reached.
- Retry only calls that are safe to repeat. A read can be retried; a payment or a sent message cannot, unless the receiving system deduplicates it.
- Count retries in the log. A call that always needs two attempts is a slow failure that will one day need three.
Hard limits: stop and report what finished
A spent quota, an expired login or a revoked permission will not clear with a retry, and retrying burns time and sometimes money. When our experiment account hit its usage limit (number 1), the run stopped and we reported the 42 completed calls as the result, with the shortfall stated next to it, in our hallucination test. Reporting the partial result honestly mattered more than finishing: a test that quietly drops its failed calls reads as a cleaner result than it is.
For an agent, this kind of failure is a reason to hand back to a person. Anthropic's guidance on building effective agents describes agents getting "ground truth" from the environment at each step and pausing for human feedback when they hit a blocker; a quota or a login is that kind of blocker.
Environment failures: check from a second place before you believe it
These are the dangerous ones, because the tool reports a clear answer about the target when the answer is about the tool.
In number 2, our quality gate failed a post in CI because a government PDF was unreachable. From a laptop in India it loaded fine; the CI machines run outside India and could not reach the host. The link was valid for readers in India and broken for the check, so we kept the source in our evidence notes and removed the link from the post.
Number 4 was subtler. Our security audit tested whether the website still accepted TLS 1.0 and 1.1, two retired versions of the encryption protocol, and the test said it refused them. The refusal came from the local copy of OpenSSL, which turns those versions off on its own side, so the connection failed before our server was asked. We noticed only because the hosting dashboard showed the minimum version as TLS 1.0, which contradicted the test. With the tool's restriction lowered, the server accepted both. We fixed the setting and corrected the audit, as described in our website security checklist.
The recovery for this kind is a second vantage point: another machine, another network, another tool, or a system that records the setting directly. A rule that would have caught both cases: before reporting that a target refused something, confirm the tool itself was willing to try.
Wrong moment: wait on a condition only the new state can meet
Number 3 was a call that succeeded at the wrong time. After each release, our pipeline tells search engines that pages have changed. The first version waited until a file on the live site answered correctly, but the old build already served that file, so the wait ended at once and the notification went out before the new pages existed. The fix waits for two things only the new release can produce: the hosting platform's build status for the new commit, and a sitemap that lists every post due that day. The details are in our IndexNow post.
The general rule: when an agent waits for something to finish, the signal has to be something the previous state could not already show.
Repeats and wrong targets: make writes idempotent and check what you are writing to
Number 6 came from a script that turned each draft into a page file named by date and slug. When we moved two posts to an earlier date, the script wrote new files and left the old ones in place, so each post would have appeared twice. We caught it before the release. The script now deletes any other dated file for the same slug before writing, so running it once or five times, with any date, leaves one file per post.
Number 7 is the failure where every tool call succeeds. After the website moved to a new branch, the scheduled writer's instructions still checked out the old one. Its commands would have worked, against a branch that no longer fed the live site. A review found it, and the instructions now name the new branch and run its checks. An agent that confirms its target before acting (which branch, which account, which environment) turns this silent success into a visible stop.
Telling the kinds apart
| Signal | Most likely kind | Recovery |
|---|---|---|
| Timeout, connection reset, 429 or 503 | Transient | Retry with growing delay and a cap |
| 401, 403, "quota exceeded", "limit reached" | Hard limit | Stop, report what finished, hand to a person |
| Works in one place and fails in another, or contradicts another source | Environment | Re-check from a second vantage point before acting on it |
| Success, but the result describes the old state | Wrong moment | Wait on a signal only the new state can give |
| Success, and the output appears twice or in the wrong place | Repeat or wrong target | Make the write idempotent; assert the target first |
This table assumes the agent logs enough to classify a failure after the fact: the tool, its input, the exact error, the attempt number and where the call ran from. Without the last of those, the two environment failures above would have looked like problems with the targets.
These recovery rules sit inside a wider set of controls for agents in production, which we cover in what safeguards should control an AI agent in production. If your agents fail in ways you cannot yet classify, tell us what you are seeing.
