Tool Errors and Retries: Letting Claude Recover Without Looping

Table of Contents

1. Why Tool Errors Matter in Production Agents
2. The Cost of Unhandled Failures
3. Claude’s Tool Error Surface
4. Retry Policies That Work
5. Context and Budget Management
6. Self-Correction Without Looping
7. Real-World Implementation Patterns
8. Monitoring and Observability
9. Avoiding Common Pitfalls
10. Next Steps and Deployment

---

Why Tool Errors Matter in Production Agents {#why-tool-errors-matter}

When Claude calls a tool—whether it’s a database query, API endpoint, or webhook—three things can go wrong: the tool itself fails, Claude misunderstands the tool’s response, or the tool returns an error that Claude doesn’t know how to interpret.

In development, these failures are obvious. You see them in logs, fix the tool definition, and move on. In production, they’re silent killers. An agent that can’t recover from a tool error either loops forever (burning tokens and budget), halts mid-task (leaving users waiting), or returns a hallucinated answer (worse than admitting defeat).

At PADISO, we’ve shipped agentic AI systems for Sydney-based founders and enterprise operators across finance, healthcare, and supply chain. We’ve learned that tool error handling isn’t a nice-to-have—it’s the difference between a $50 API call and a $5,000 runaway loop. The Padiso default retry policy is built on patterns we’ve validated across 50+ production deployments.

This guide walks you through the patterns we ship, the reasoning behind them, and how to implement them in your own Claude-powered agents.

The Cost of Unhandled Failures {#the-cost-of-unhandled-failures}

Let’s be concrete about the stakes. Imagine an agent that queries a database, receives a timeout error, and doesn’t know what to do. Without explicit error handling, here’s what typically happens:

Scenario 1: Silent Retry Loop Claude sees the error message and decides to try again. Same timeout. It tries again. After 5–10 retries, it’s burned 50,000 tokens ($0.50 in input costs alone) and still hasn’t solved the problem. The user is left waiting.

Scenario 2: Hallucinated Recovery Claude interprets the error as “the database is temporarily unavailable” and fabricates a response based on its training data. The user gets wrong information, makes a bad decision, and you get blamed.

Scenario 3: Cascading Failures The agent retries with slightly different parameters, which triggers a different error, which it interprets as a new problem, which it tries to solve with a different tool. Three tools deep, the agent is lost, context is bloated, and you’re tracking down a failure that spans multiple systems.

According to research on AI agent reliability, error recovery scaffolding is the single biggest determinant of whether agents ship reliably or become expensive liabilities. The difference between a well-designed retry policy and no policy at all is often 10–50x in cost per task and 100x in time-to-resolution for failures.

We’ve seen operators at mid-market companies spend weeks debugging agent failures that could have been prevented with a 20-line error handler. We’ve also seen founders blow through seed-stage budgets because their agents looped on tool errors without bounds.

The good news: error handling for Claude agents is straightforward. It requires discipline, not genius.

Claude’s Tool Error Surface {#claude-tool-error-surface}

Before you can handle errors, you need to understand where they come from.

Claude interacts with tools in a specific way. You define a set of tools in the system prompt or via the Tools API. Claude decides whether to call a tool, generates a tool call with parameters, and your code executes it. Claude then sees the result (success or error) and decides what to do next.

There are four categories of errors that can occur:

1. Tool Definition Errors

You’ve told Claude about a tool, but the definition is incomplete or wrong. For example:

• The tool name doesn’t match what your code expects.
• A required parameter is missing from the definition.
• The parameter type is ambiguous (is date a string or a timestamp?).

Claude will call the tool anyway, your code will reject it, and Claude will see an error like "Tool 'query_database' not found" or "Missing required parameter: 'table_name'". Claude can usually recover from these by adjusting the call, but it wastes tokens and adds latency.

2. Tool Execution Errors

The tool exists, Claude called it correctly, but the underlying system failed. Examples:

• Database connection timeout.
• API rate limit exceeded.
• File system permission denied.
• Network unreachable.

These are transient in many cases. A retry with exponential backoff often succeeds. But if you don’t tell Claude about the retry policy, it’ll keep trying with the same parameters and the same failure.

3. Tool Result Errors

The tool executed, but returned an error in its response. For example:

• A database query returned “No rows found.”
• An API returned a 404 (resource not found).
• A validation service returned “Email format invalid.”

These are usually not transient. Retrying won’t help. Claude needs to understand that the error is semantic, not technical, and adjust its strategy.

4. Claude Misinterpretation Errors

The tool returned a valid result, but Claude misunderstood it. For example:

• The tool returned a list of 100 items, and Claude thought it was a single item.
• The tool returned a nested JSON structure, and Claude extracted the wrong field.
• The tool returned a success code, but Claude interpreted it as a failure.

These are harder to catch programmatically, but clear error messages and structured responses help.

According to Anthropic’s documentation, Claude is trained to handle tool errors gracefully if you provide them in the right format. The key is to return error messages that are specific, actionable, and don’t repeat information Claude already knows.

Retry Policies That Work {#retry-policies-that-work}

The Padiso default retry policy is built on three principles:

1. Retry only transient errors. If a tool fails because of a timeout, retry. If it fails because of a permission error, don’t.
2. Use exponential backoff. The first retry happens immediately, the second after 1 second, the third after 2 seconds, then 4, 8, 16. This gives transient systems time to recover without burning tokens.
3. Set hard limits. Never retry more than 3–5 times. If it’s still failing, admit defeat and escalate to the user.

Here’s the pattern in pseudocode:

function call_tool_with_retry(tool_name, parameters, max_retries=3):
  for attempt in 1..max_retries:
    try:
      result = execute_tool(tool_name, parameters)
      if result.is_error:
        if is_transient_error(result.error_code):
          wait(2^(attempt-1) seconds)
          continue
        else:
          return result  # Don't retry non-transient errors
      return result
    catch exception:
      if is_transient_error(exception.type):
        wait(2^(attempt-1) seconds)
        continue
      else:
        throw exception
  
  return error("Tool failed after max retries")

The key decision: which errors are transient? Here’s a practical breakdown:

Transient (retry):

• HTTP 429 (rate limit)
• HTTP 503 (service unavailable)
• HTTP 504 (gateway timeout)
• Network timeouts
• Database connection timeouts
• Temporary lock errors

Non-transient (don’t retry):

• HTTP 400 (bad request)
• HTTP 401 (unauthorized)
• HTTP 403 (forbidden)
• HTTP 404 (not found)
• Database syntax errors
• Permission denied
• Invalid parameter type

When you return an error to Claude, include the error code and a brief explanation:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "API rate limit exceeded. Retry after 60 seconds.",
  "retry_after_seconds": 60
}

Claude will see this and understand that the error is transient. It won’t retry immediately (because you’ve told it to wait), but it knows that the problem is solvable.

For non-transient errors, be equally clear:

{
  "error": "INVALID_PARAMETER",
  "message": "Parameter 'user_id' must be a positive integer. Received: 'abc123'.",
  "retry_after_seconds": null
}

Claude will see retry_after_seconds: null (or its absence) and understand that retrying won’t help. It will adjust its strategy—ask the user for a valid ID, try a different tool, or escalate.

Context and Budget Management {#context-budget-management}

Retries are cheap in terms of API calls, but expensive in terms of context. Every retry adds the tool call, the error response, and Claude’s reasoning about the retry to the conversation history.

Imagine an agent that retries a tool 5 times. That’s 5 tool calls, 5 error messages, and 5 decision points in the context window. On a 200k-token window, that’s fine. On a 4k-token window (older models), that’s a problem.

Here’s how to manage context efficiently:

1. Deduplicate Error Messages

If Claude retries the same tool with the same parameters and gets the same error, don’t return the full error message again. Instead:

{
  "error": "TIMEOUT",
  "message": "[Retry 2/3] Still timing out. Waiting 2 seconds before next attempt.",
  "retry_after_seconds": 2
}

Claude will understand that this is a repeated error without you repeating all the details.

2. Summarise Long Tool Results

If a tool returns 10,000 characters of data, Claude doesn’t need all of it. Summarise:

{
  "status": "success",
  "message": "Query returned 5,432 rows. Showing first 10 and last 10 rows. Total size: 2.3 MB.",
  "rows": [...10 rows...],
  "summary": "Results span 2024-01-01 to 2024-12-31. Top category is 'Electronics' (1,203 rows). No nulls detected."
}

Claude can work with the summary and ask for specific rows if needed, without loading the entire dataset into context.

3. Set Token Budgets Per Task

Before an agent starts a task, tell it how many tokens it has to spend. If it’s approaching the limit, it should wrap up:

You have 10,000 tokens to complete this task. You've used 7,500 so far.
If you need to retry a tool, keep the retry budget in mind.

This prevents runaway loops. Claude will make faster decisions and avoid unnecessary retries.

4. Use Structured Responses

Structured responses (JSON) are more token-efficient than prose. Instead of:

The database query failed because the connection timed out after 30 seconds.
This is a temporary issue and the query should be retried.

Use:

{
  "error": "TIMEOUT",
  "transient": true,
  "retry_after": 2
}

Same information, fewer tokens.

Self-Correction Without Looping {#self-correction-without-looping}

Retries are for transient errors. Self-correction is for Claude’s own mistakes—misunderstanding a tool’s response, calling the wrong tool, or using the wrong parameters.

The difference is crucial. A retry means “try again with the same strategy.” Self-correction means “try again with a different strategy.”

Here’s how to enable self-correction without creating infinite loops:

1. Provide Explicit Feedback

When Claude makes a mistake, don’t just say “error.” Tell it what went wrong:

{
  "error": "INVALID_CALL",
  "message": "The tool 'query_database' expects parameter 'sql' to be a SELECT statement. You provided an INSERT statement. Use 'execute_query' for INSERT/UPDATE/DELETE operations.",
  "suggestion": "Retry with 'execute_query' tool instead."
}

Claude will learn from the feedback and adjust.

2. Limit Self-Correction Attempts

Set a hard limit on how many times Claude can retry the same task:

You've attempted this task 3 times. If the 4th attempt fails, escalate to the user.

This prevents infinite loops. Claude will be more careful with each attempt, knowing that it has limited chances.

3. Vary the Approach

If Claude’s first attempt failed, encourage it to try a different tool or strategy:

{
  "error": "TOOL_FAILED",
  "message": "The 'query_database' tool failed. Try the 'search_database' tool instead, which is more lenient with malformed queries.",
  "alternatives": ["search_database", "raw_sql_query"]
}

Claude will see the alternatives and pick a different approach.

4. Use Confidence Scoring

If Claude is uncertain about a tool call, ask it to rate its confidence:

Before calling a tool, rate your confidence in the tool choice (1-10).
If your confidence is below 5, ask the user for clarification instead.

This reduces the number of failed tool calls in the first place.

According to research on how users respond to AI errors, explicit feedback and confidence scoring significantly improve user trust and agent reliability. Users would rather have an agent that admits uncertainty than one that retries blindly.

Real-World Implementation Patterns {#real-world-implementation}

Let’s walk through concrete examples. These patterns are based on what we ship at PADISO for our clients.

Pattern 1: Database Query with Retry

You’re building an agent that queries a data warehouse. Timeouts are common during peak hours.

import anthropic
import time
from typing import Any

client = anthropic.Anthropic()

def query_database(sql: str, max_retries: int = 3) -> dict[str, Any]:
    """Execute a SQL query with exponential backoff retry."""
    for attempt in range(max_retries):
        try:
            # Simulate database call
            result = execute_sql(sql)
            return {"status": "success", "data": result}
        except TimeoutError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt
                return {
                    "error": "TIMEOUT",
                    "message": f"Query timed out. Retrying in {wait_time}s...",
                    "retry_after_seconds": wait_time,
                    "attempt": attempt + 1,
                    "max_attempts": max_retries
                }
            else:
                return {
                    "error": "TIMEOUT_EXHAUSTED",
                    "message": "Query timed out after 3 attempts. Please try again later or contact support."
                }
        except SyntaxError as e:
            return {
                "error": "SYNTAX_ERROR",
                "message": f"SQL syntax error: {str(e)}. Check your query and try again."
            }

def run_agent_with_tools():
    tools = [
        {
            "name": "query_database",
            "description": "Execute a SQL SELECT query on the data warehouse.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {
                        "type": "string",
                        "description": "A valid SQL SELECT statement"
                    }
                },
                "required": ["sql"]
            }
        }
    ]
    
    messages = [
        {"role": "user", "content": "How many orders did we receive yesterday?"}
    ]
    
    while True:
        response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )
        
        # Check if Claude wants to use a tool
        if response.stop_reason == "tool_use":
            for block in response.content:
                if block.type == "tool_use":
                    tool_name = block.name
                    tool_input = block.input
                    tool_use_id = block.id
                    
                    # Execute the tool
                    if tool_name == "query_database":
                        result = query_database(tool_input["sql"])
                    
                    # Add Claude's response and tool result to messages
                    messages.append({"role": "assistant", "content": response.content})
                    messages.append({
                        "role": "user",
                        "content": [
                            {
                                "type": "tool_result",
                                "tool_use_id": tool_use_id,
                                "content": str(result)
                            }
                        ]
                    })
        else:
            # Claude has finished
            final_response = ""
            for block in response.content:
                if hasattr(block, "text"):
                    final_response += block.text
            return final_response

Key points:

• The query_database function handles retries internally.
• It returns structured error responses that Claude can understand.
• It uses exponential backoff (2^attempt seconds).
• It stops after 3 attempts and admits defeat.

Pattern 2: API Call with Rate Limit Handling

You’re building an agent that calls a third-party API. Rate limits are strict.

import requests
from typing import Optional

def call_external_api(
    endpoint: str,
    params: dict,
    max_retries: int = 3,
    initial_backoff: float = 1.0
) -> dict[str, Any]:
    """Call an external API with rate limit awareness."""
    backoff = initial_backoff
    
    for attempt in range(max_retries):
        try:
            response = requests.get(endpoint, params=params, timeout=10)
            
            # Check for rate limit
            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", backoff))
                return {
                    "error": "RATE_LIMIT",
                    "message": f"API rate limit exceeded.",
                    "retry_after_seconds": retry_after,
                    "attempt": attempt + 1
                }
            
            # Check for server errors (transient)
            if response.status_code in [500, 502, 503, 504]:
                if attempt < max_retries - 1:
                    return {
                        "error": "SERVER_ERROR",
                        "message": f"API returned {response.status_code}. Retrying...",
                        "retry_after_seconds": backoff,
                        "attempt": attempt + 1
                    }
                else:
                    return {
                        "error": "SERVER_ERROR_EXHAUSTED",
                        "message": "API server is temporarily unavailable. Try again later."
                    }
            
            # Check for client errors (don't retry)
            if response.status_code in [400, 401, 403, 404]:
                return {
                    "error": f"HTTP_{response.status_code}",
                    "message": response.json().get("error", "Request failed."),
                    "retry_after_seconds": None
                }
            
            # Success
            if response.status_code == 200:
                return {
                    "status": "success",
                    "data": response.json()
                }
        
        except requests.Timeout:
            if attempt < max_retries - 1:
                return {
                    "error": "TIMEOUT",
                    "message": f"API request timed out. Retrying...",
                    "retry_after_seconds": backoff,
                    "attempt": attempt + 1
                }
        
        backoff *= 2  # Exponential backoff
    
    return {
        "error": "MAX_RETRIES_EXCEEDED",
        "message": "API request failed after multiple retries. Please try again later."
    }

Key points:

• We respect the Retry-After header from the API.
• We distinguish between transient (5xx) and non-transient (4xx) errors.
• We use exponential backoff, but reset it if the API tells us to wait longer.

Pattern 3: Chained Tools with Error Propagation

You’re building an agent that needs to call multiple tools in sequence. If one fails, the whole chain fails.

def process_order_with_tools(order_id: str) -> dict[str, Any]:
    """Process an order by calling multiple tools in sequence."""
    
    # Step 1: Get order details
    order = get_order(order_id)
    if order.get("error"):
        return order  # Propagate error
    
    # Step 2: Validate inventory
    inventory_check = check_inventory(order["data"]["items"])
    if inventory_check.get("error"):
        return {
            "error": "INVENTORY_CHECK_FAILED",
            "message": f"Cannot process order: {inventory_check['message']}",
            "original_error": inventory_check
        }
    
    # Step 3: Process payment
    payment = process_payment(order["data"]["total"])
    if payment.get("error"):
        # Payment failed—rollback inventory check
        rollback_inventory(order["data"]["items"])
        return {
            "error": "PAYMENT_FAILED",
            "message": f"Payment failed: {payment['message']}. Inventory check rolled back.",
            "original_error": payment
        }
    
    # Step 4: Create shipment
    shipment = create_shipment(order["data"]["items"], order["data"]["address"])
    if shipment.get("error"):
        # Shipment failed—refund payment and rollback inventory
        refund_payment(payment["data"]["transaction_id"])
        rollback_inventory(order["data"]["items"])
        return {
            "error": "SHIPMENT_FAILED",
            "message": f"Shipment creation failed: {shipment['message']}. Payment refunded and inventory rolled back.",
            "original_error": shipment
        }
    
    return {
        "status": "success",
        "order_id": order_id,
        "shipment_id": shipment["data"]["id"]
    }

Key points:

• Each step checks for errors before proceeding.
• If a step fails, we propagate the error and provide context about what went wrong.
• We include rollback logic for critical operations.
• Claude can see the full error chain and understand what failed and why.

Monitoring and Observability {#monitoring-observability}

Error handling is only useful if you can see what’s happening. You need to monitor:

1. Tool Call Success Rate

Track the percentage of tool calls that succeed on the first attempt:

import logging
from datetime import datetime

class ToolCallMetrics:
    def __init__(self):
        self.total_calls = 0
        self.successful_calls = 0
        self.failed_calls = 0
        self.retried_calls = 0
    
    def record_call(self, tool_name: str, success: bool, retries: int = 0):
        self.total_calls += 1
        if success:
            self.successful_calls += 1
        else:
            self.failed_calls += 1
        if retries > 0:
            self.retried_calls += 1
        
        logging.info(
            f"Tool call: {tool_name} | Success: {success} | Retries: {retries}"
        )
    
    def get_success_rate(self) -> float:
        if self.total_calls == 0:
            return 0.0
        return (self.successful_calls / self.total_calls) * 100

If your success rate is below 95%, you have a problem. Investigate the most common failures and fix the tool definitions or error handling.

2. Token Usage by Tool

Track how many tokens each tool consumes:

class TokenUsageMetrics:
    def __init__(self):
        self.tool_tokens = {}  # {tool_name: total_tokens}
    
    def record_tool_usage(self, tool_name: str, input_tokens: int, output_tokens: int):
        if tool_name not in self.tool_tokens:
            self.tool_tokens[tool_name] = {"input": 0, "output": 0, "calls": 0}
        
        self.tool_tokens[tool_name]["input"] += input_tokens
        self.tool_tokens[tool_name]["output"] += output_tokens
        self.tool_tokens[tool_name]["calls"] += 1
    
    def get_average_tokens_per_call(self, tool_name: str) -> float:
        if tool_name not in self.tool_tokens:
            return 0.0
        data = self.tool_tokens[tool_name]
        total = data["input"] + data["output"]
        return total / data["calls"]

If a tool suddenly uses 10x more tokens than usual, something is wrong. Either Claude is retrying excessively, or the tool is returning bloated responses.

3. Error Categories

Grouping errors by type helps you spot patterns:

class ErrorMetrics:
    def __init__(self):
        self.errors = {}  # {error_code: count}
    
    def record_error(self, error_code: str, tool_name: str, message: str):
        key = f"{tool_name}:{error_code}"
        self.errors[key] = self.errors.get(key, 0) + 1
        
        logging.warning(
            f"Tool error: {tool_name} | Code: {error_code} | Message: {message}"
        )
    
    def get_top_errors(self, limit: int = 10) -> list:
        return sorted(
            self.errors.items(),
            key=lambda x: x[1],
            reverse=True
        )[:limit]

If you see a spike in TIMEOUT errors, your database might be overloaded. If you see a spike in RATE_LIMIT errors, you might need to upgrade your API plan.

4. End-to-End Task Latency

Track how long it takes Claude to complete a task, including retries:

import time
from contextlib import contextmanager

class LatencyMetrics:
    def __init__(self):
        self.task_latencies = []  # [latency_ms, ...]
    
    @contextmanager
    def measure_task(self, task_name: str):
        start = time.time()
        try:
            yield
        finally:
            elapsed_ms = (time.time() - start) * 1000
            self.task_latencies.append(elapsed_ms)
            logging.info(f"Task '{task_name}' completed in {elapsed_ms:.1f}ms")
    
    def get_percentile(self, percentile: int) -> float:
        if not self.task_latencies:
            return 0.0
        sorted_latencies = sorted(self.task_latencies)
        index = int(len(sorted_latencies) * percentile / 100)
        return sorted_latencies[index]

If the 95th percentile latency spikes, you have a problem. Investigate whether it’s due to retries, slow tools, or slow Claude responses.

At PADISO, we’ve seen clients reduce their agentic AI costs by 40–60% just by implementing proper monitoring and fixing the top 5 error categories. You can’t improve what you don’t measure.

Avoiding Common Pitfalls {#avoiding-pitfalls}

Here are the mistakes we see repeatedly:

Pitfall 1: Retry Without Backoff

If you retry immediately without waiting, you’re just hammering the same failing system. The database is still overloaded, the API is still rate-limited, and Claude is burning tokens for nothing.

Wrong:

for i in range(5):
    result = call_tool()
    if result.error:
        continue  # Retry immediately

Right:

for i in range(5):
    result = call_tool()
    if result.error and is_transient(result.error):
        time.sleep(2 ** i)  # Exponential backoff
        continue

Pitfall 2: Retrying Non-Transient Errors

If Claude calls a tool with the wrong parameters, retrying won’t help. You need to give Claude feedback and let it adjust.

Wrong:

result = query_database("INSERT INTO users...")
if result.error:
    time.sleep(1)
    result = query_database("INSERT INTO users...")  # Same error

Right:

result = query_database("INSERT INTO users...")
if result.error and result.error_code == "WRONG_TOOL":
    return {
        "error": "WRONG_TOOL",
        "message": "Use 'execute_query' for INSERT statements, not 'query_database'."
    }

Pitfall 3: Unbounded Retries

If you don’t set a maximum retry count, Claude can loop forever. We’ve seen agents burn $500+ because they kept retrying a tool that was permanently down.

Wrong:

while True:
    result = call_tool()
    if result.success:
        break
    time.sleep(1)

Right:

for attempt in range(3):
    result = call_tool()
    if result.success:
        break
    if attempt == 2:
        return error("Tool failed after 3 attempts")

Pitfall 4: Bloated Error Messages

If your error messages are 1,000 characters long, Claude will include them in context for every retry. That’s wasteful.

Wrong:

{
  "error": "DATABASE_ERROR",
  "message": "The database query failed because the connection pool was exhausted. This typically happens when there are more concurrent connections than the pool size. The pool size is currently set to 20, and there are currently 25 active connections. To fix this, you can either increase the pool size or reduce the number of concurrent connections. Here's how to increase the pool size: [full instructions]..."
}

Right:

{
  "error": "CONNECTION_POOL_EXHAUSTED",
  "message": "Database connection pool exhausted (25/20). Retry in 5s.",
  "retry_after_seconds": 5
}

Pitfall 5: Silent Failures

If a tool fails and you return an empty result, Claude will assume it succeeded and might make decisions based on false data.

Wrong:

try:
    result = call_tool()
except Exception:
    return {}  # Looks like success

Right:

try:
    result = call_tool()
except Exception as e:
    return {
        "error": "TOOL_FAILED",
        "message": str(e)
    }

Next Steps and Deployment {#next-steps}

Here’s how to implement this in your own agents:

Step 1: Audit Your Current Tool Definitions

For each tool, ask:

• Is the description clear and specific?
• Are all required parameters documented?
• Are the parameter types unambiguous?
• Does the tool return structured error responses?

If the answer to any of these is “no,” fix it before deploying.

Step 2: Implement Error Handling

Add a retry wrapper around each tool. Start with the Padiso default:

• Max 3 retries
• Exponential backoff (1s, 2s, 4s)
• Distinguish transient vs. non-transient errors
• Return structured error responses

Step 3: Add Monitoring

Instrument your agent to track:

• Tool call success rate
• Token usage per tool
• Error categories
• End-to-end task latency

Set alerts for:

• Success rate below 90%
• Average tokens per call 2x higher than baseline
• New error types appearing
• 95th percentile latency above 30 seconds

Step 4: Test Error Paths

Don’t just test the happy path. Simulate:

• Tool timeouts
• API rate limits
• Database connection failures
• Invalid tool parameters
• Empty result sets

Make sure Claude handles each gracefully.

Step 5: Deploy and Iterate

Start with a small cohort of users. Monitor the metrics. Fix the top error categories. Expand to more users.

At PADISO, we’ve found that error handling improvements compound. The first iteration cuts costs by 20%. The second cuts another 20%. By the third, you’re at 40–50% total savings.

Conclusion

Tool errors are inevitable. The question is whether your agent recovers gracefully or spirals into expensive loops.

The patterns in this guide are battle-tested across 50+ production deployments. They work because they’re based on three principles:

1. Distinguish transient from non-transient errors. Retry the former, escalate the latter.
2. Use exponential backoff. Give systems time to recover without burning tokens.
3. Set hard limits. Never retry indefinitely. Admit defeat and escalate.

If you’re building agentic AI systems—whether you’re a founder at a seed-stage startup or an operator modernising enterprise workflows—error handling is non-negotiable. It’s the difference between a $50 task and a $5,000 disaster.

For founders and CTOs looking to ship AI products reliably, PADISO’s AI & Agents Automation service includes error-handling architecture as standard. We’ve also documented real production failures and what we learned from them in our agentic AI production horror stories guide.

If you’re running a mid-market or enterprise modernisation project, error handling is part of Platform Design & Engineering. We’ve helped operators at companies across finance, healthcare, and supply chain reduce their agentic AI costs by 40–60% through better error handling and observability.

Start with the Padiso default retry policy. Measure everything. Fix the top errors. Iterate. Your future self (and your budget) will thank you.

---

Additional Resources

For deeper technical context, we recommend:

• The Anthropic documentation on tool use provides the canonical specification for how Claude handles tool calls and errors.
• Research on AI agent reliability explores error recovery scaffolding and its impact on agent robustness.
• NIST guidelines for AI risk management cover error detection and recovery in production systems.
• Analysis of AI system vulnerabilities highlights common failure modes in tool-calling architectures.

For Sydney-based founders and operators building agentic AI systems, PADISO offers fractional CTO services that include error-handling architecture design. We’ve also published guides on agentic AI vs. traditional automation, AI automation for customer service, and AI orchestration patterns that all build on solid error-handling foundations.

If you’re implementing SOC 2 or ISO 27001 compliance for your AI systems, error handling and observability are audit-critical. We’ve helped teams pass security audits via Security Audit services that include tool-calling architecture reviews.

For private equity firms and portfolio companies running AI transformation or platform modernisation, error-handling patterns are part of our technology due diligence and platform consolidation services. We’ve assessed and remediated error handling in 50+ production agent systems, identifying cost and reliability improvements worth millions in aggregate value creation.