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
| 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, and every error code on Error codes.
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.