# How AI agents should handle API failures

Errors, empty answers and wrong answers: how an agent can tell them apart, when to retry, when to switch provider, and how not to pay for failures.

An agent should treat an API failure as one of three things: an error (retry once), an empty answer (try another provider), or a wrong answer (check before using it). The costly mistake is treating all three as success, or paying for them.

## Three kinds of failure

Kinds of API failure and what to do

| Kind | Example | What to do |
|---|---|---|
| Error or timeout | HTTP 500, or no answer in 30 seconds | Retry once, then switch |
| Empty answer | No email found, zero search results | Try the next provider |
| Wrong answer | A catch-all email marked valid, a captcha page instead of content | Check the result against a rule before using it |

## Retry rules that work

- Retry once after an error or a timeout, not in a loop.
- Send an idempotency key, so a retry can't buy twice.
- Don't retry an error that says the input is wrong. Fix the input.
- Cap the total price of a request, so retries can't run up a bill.

## Check before you use it

The failures that hurt most aren't errors. They're answers that look fine: an email that bounces, a page that's really a block screen. Write the check down as a rule, and run it on every result.

## How Arettic handles it

- **Errors and timeouts.** Each attempt is cut off after 30 seconds, with one retry. A provider failure costs nothing.
- **Empty answers.** With `fallback: true`, the next-ranked tool runs once.
- **Wrong answers.** Every guaranteed job has a published pass rule. A result that fails it is refunded and its data withheld, and your agent gets the reason.
- **Duplicates.** With an `idempotency_key`, a retry returns the first answer and is charged once.

Every rule is on [Pass rules](/docs/pass-rules), and every error code on [Error codes](/docs/errors).

## Questions

### Should an agent retry a failed API call?

Once, after an error or a timeout. After that, switch provider or stop. Never retry an error that says the input is invalid.

### Do I pay for failed calls on Arettic?

No. A call the provider fails costs nothing, and a guaranteed job that fails its check is refunded.

Updated 2026-10-23. This page as HTML: https://arettic.com/guides/handle-api-failures-in-agents · Markdown: https://arettic.com/guides/handle-api-failures-in-agents.md · JSON: https://arettic.com/guides/handle-api-failures-in-agents.json