{
  "page": "guides/handle-api-failures-in-agents",
  "title": "How AI agents should handle API failures",
  "path": "/guides/handle-api-failures-in-agents",
  "kind": "guide",
  "description": "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.",
  "updated": "2026-10-23",
  "blocks": [
    {
      "type": "p",
      "text": "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."
    },
    {
      "type": "h2",
      "id": "kinds",
      "text": "Three kinds of failure"
    },
    {
      "type": "table",
      "caption": "Kinds of API failure and what to do",
      "head": [
        "Kind",
        "Example",
        "What to do"
      ],
      "rows": [
        [
          "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"
        ]
      ]
    },
    {
      "type": "h2",
      "id": "retries",
      "text": "Retry rules that work"
    },
    {
      "type": "list",
      "items": [
        "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."
      ]
    },
    {
      "type": "h2",
      "id": "check",
      "text": "Check before you use it"
    },
    {
      "type": "p",
      "text": "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."
    },
    {
      "type": "h2",
      "id": "arettic",
      "text": "How Arettic handles it"
    },
    {
      "type": "list",
      "items": [
        "**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."
      ]
    },
    {
      "type": "p",
      "text": "Every rule is on [Pass rules](/docs/pass-rules), and every error code on [Error codes](/docs/errors)."
    }
  ],
  "questions": [
    {
      "question": "Should an agent retry a failed API call?",
      "answer": "Once, after an error or a timeout. After that, switch provider or stop. Never retry an error that says the input is invalid."
    },
    {
      "question": "Do I pay for failed calls on Arettic?",
      "answer": "No. A call the provider fails costs nothing, and a guaranteed job that fails its check is refunded."
    }
  ]
}