Error Handling and Graceful Degradation in Claude Agents: Production Patterns

Most Claude agent tutorials stop at the happy path. The tool returns data, the model parses it cleanly, the response is perfect. That’s not production. In production, your database connection times out at 2 AM, the third-party API returns a 429 with no Retry-After header, and Claude produces JSON that’s almost valid but has a trailing comma. Claude agent error handling is what separates a demo that impresses and a system that runs reliably for months.

This article covers the patterns I’ve used in production agent systems: retry logic that doesn’t hammer APIs, fallback chains that degrade gracefully, and structured error responses that keep the agent on track instead of hallucinating its way through a broken tool call.

Why Agent Error Handling Is Different From Regular API Error Handling

In a simple API integration, an error stops the request and you return a 500. In an agent loop, an error in one tool call is one step in a multi-step reasoning process. If you let it crash, you lose context, waste tokens on the prior conversation, and give the user a confusing failure. If you handle it poorly — returning nothing, or returning a vague error string — the model often hallucinates a plausible-sounding result instead of acknowledging the failure.

The core challenge: the agent needs enough signal to decide what to do next, not just that something went wrong. There’s a meaningful difference between “the database is down” (retry or abort), “the record doesn’t exist” (proceed with defaults), and “your query syntax was invalid” (the model needs to reformulate).

The Three Failure Modes You’ll Actually Hit

• Transient infrastructure failures — timeouts, rate limits, network blips. Retryable with backoff.
• Semantic failures — the tool ran, but returned data that doesn’t match what the model expected. Malformed JSON, missing fields, unexpected schema.
• Logic failures — the model called a tool with invalid parameters, or in the wrong sequence. Requires reformulation, not retry.

Your error handling layer needs to distinguish between these. Retrying a logic failure burns tokens and time with zero benefit.

Retry Logic With Exponential Backoff

The baseline pattern for transient failures. The key implementation detail most tutorials skip: you need to pass the error back to the agent with enough context to decide whether retrying makes sense, rather than silently retrying in the background and pretending nothing happened.

import anthropic
import time
import random
from typing import Any, Callable

client = anthropic.Anthropic()

def with_retry(
    fn: Callable,
    max_attempts: int = 3,
    base_delay: float = 1.0,
    max_delay: float = 30.0,
    retryable_exceptions: tuple = (TimeoutError, ConnectionError)
) -> Any:
    """
    Retry wrapper with exponential backoff + jitter.
    Returns (result, None) on success, (None, error_context) on final failure.
    """
    last_error = None
    
    for attempt in range(max_attempts):
        try:
            return fn(), None
        except retryable_exceptions as e:
            last_error = e
            if attempt == max_attempts - 1:
                break
            # Exponential backoff with jitter to avoid thundering herd
            delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
            time.sleep(delay)
        except Exception as e:
            # Non-retryable — fail immediately with error context
            return None, {
                "error_type": "non_retryable",
                "error_class": type(e).__name__,
                "message": str(e),
                "should_retry": False
            }
    
    return None, {
        "error_type": "exhausted_retries",
        "error_class": type(last_error).__name__,
        "message": str(last_error),
        "attempts": max_attempts,
        "should_retry": False
    }

The return signature matters here. Instead of raising, you return a structured error context dict. When you pass this back to the tool result in the agent loop, Claude can reason about it — “the database is unreachable after 3 attempts, I should tell the user we can’t complete this right now” rather than inventing an answer.

Structured Tool Error Responses

Anthropic’s tool use API lets you return tool results with an is_error flag. Use it. An error result that the model can read is dramatically better than a silent failure or a generic exception string.

def execute_tool_call(tool_name: str, tool_input: dict) -> dict:
    """
    Wraps tool execution and returns a structured result for the agent loop.
    Always returns a dict suitable for tool_result content.
    """
    try:
        result = dispatch_tool(tool_name, tool_input)
        return {
            "type": "tool_result",
            "content": result,
            "is_error": False
        }
    except ValueError as e:
        # Parameter validation failed — model should reformulate
        return {
            "type": "tool_result",
            "content": f"Invalid parameters: {str(e)}. Please check the tool schema and try again with corrected inputs.",
            "is_error": True
        }
    except TimeoutError:
        return {
            "type": "tool_result", 
            "content": "Tool call timed out after 10 seconds. The service may be temporarily unavailable.",
            "is_error": True
        }
    except Exception as e:
        # Catch-all — log this for debugging but give the model something useful
        return {
            "type": "tool_result",
            "content": f"Unexpected error ({type(e).__name__}): {str(e)}",
            "is_error": True
        }

The error messages in those strings are written for Claude to read, not for a human stack trace. That’s intentional. “Please check the tool schema and try again” gives the model an explicit action to take. Dumping a raw Python traceback does not.

Handling Malformed Model Outputs

Tool inputs coming from the model are usually well-structured — the API enforces the schema. But if you’re using Claude to produce structured output via text completion (without tool use), you’ll hit malformed JSON regularly, especially with Haiku at complex schemas.

import json
import re

def parse_structured_output(raw_text: str, expected_schema: dict) -> tuple[dict | None, str | None]:
    """
    Attempts to extract valid JSON from model output.
    Returns (parsed_dict, None) on success, (None, error_message) on failure.
    """
    # First try: direct parse
    try:
        return json.loads(raw_text.strip()), None
    except json.JSONDecodeError:
        pass
    
    # Second try: extract JSON block from markdown code fence
    code_block = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', raw_text, re.DOTALL)
    if code_block:
        try:
            return json.loads(code_block.group(1)), None
        except json.JSONDecodeError:
            pass
    
    # Third try: find the outermost JSON object
    json_match = re.search(r'\{.*\}', raw_text, re.DOTALL)
    if json_match:
        try:
            return json.loads(json_match.group(0)), None
        except json.JSONDecodeError:
            pass
    
    # All attempts failed — return error with raw output for logging
    return None, f"Could not parse JSON from output (length: {len(raw_text)})"

In my experience, the regex extraction catches about 80% of the cases where the model wraps JSON in markdown or adds commentary around it. The remaining 20% genuinely need a retry with a more explicit prompt — something like “Respond with only valid JSON, no explanation.”

When to Re-Prompt vs When to Abort

One retry on a parse failure is reasonable. Two is probably a model confusion issue that won’t self-resolve. At that point, either simplify your schema, switch to tool use (which enforces structure), or return a degraded response to the user rather than burning more tokens.

Fallback Chains and Graceful Degradation

The most underused pattern in agent systems is the fallback chain — a ranked sequence of strategies where each step produces a less complete but still useful result. This is what makes the difference between “sorry, something went wrong” and a system that keeps delivering value under partial failure.

from dataclasses import dataclass
from typing import Optional

@dataclass
class AgentResult:
    content: str
    confidence: str  # "full", "partial", "fallback"
    missing_data: list[str]

def get_customer_summary(customer_id: str) -> AgentResult:
    """
    Attempts full data fetch, degrades gracefully if components fail.
    """
    missing = []
    
    # Primary: full profile from main DB
    profile, err = with_retry(lambda: fetch_customer_profile(customer_id))
    if err:
        # Can't proceed without profile — abort
        return AgentResult(
            content="Unable to retrieve customer data at this time.",
            confidence="fallback",
            missing_data=["profile"]
        )
    
    # Secondary: purchase history (useful but not required)
    history, err = with_retry(lambda: fetch_purchase_history(customer_id))
    if err:
        missing.append("purchase_history")
        history = []  # Proceed with empty history
    
    # Tertiary: real-time segment from ML service (nice to have)
    segment, err = with_retry(lambda: fetch_ml_segment(customer_id))
    if err:
        missing.append("ml_segment")
        segment = profile.get("static_segment", "unknown")  # Use cached fallback
    
    summary = build_summary(profile, history, segment)
    
    return AgentResult(
        content=summary,
        confidence="partial" if missing else "full",
        missing_data=missing
    )

The confidence and missing_data fields aren’t decoration — pass them back to the agent. Claude can then say “I’ve summarised this customer’s profile, though purchase history wasn’t available right now” rather than presenting incomplete data as if it were complete.

Rate Limit Handling Across Multiple APIs

Production agents typically call several APIs per run. Rate limit errors need special handling because the right delay comes from the response headers, not from your backoff logic.

import httpx

def handle_rate_limit(response: httpx.Response) -> float:
    """
    Extract the correct wait time from rate limit response headers.
    Returns seconds to wait before retrying.
    """
    # Check for standard Retry-After header (in seconds or HTTP date)
    retry_after = response.headers.get("Retry-After")
    if retry_after:
        try:
            return float(retry_after)
        except ValueError:
            # It's an HTTP date format — parse it
            from email.utils import parsedate_to_datetime
            import datetime
            retry_time = parsedate_to_datetime(retry_after)
            wait = (retry_time - datetime.datetime.now(datetime.timezone.utc)).total_seconds()
            return max(wait, 0)
    
    # Anthropic-specific: x-ratelimit-reset-requests
    reset_header = response.headers.get("x-ratelimit-reset-requests", "")
    if reset_header.endswith("s"):
        try:
            return float(reset_header[:-1])
        except ValueError:
            pass
    
    # No header — default conservative wait
    return 60.0

Anthropic’s rate limit headers are documented but the format is slightly unusual (e.g., "30s" rather than "30"). The code above handles both. At current Sonnet pricing, burning a 60-second wait because you didn’t parse the header is expensive when you multiply it across many users.

Agent Loop Circuit Breaker

The pattern I see missing most often: a circuit breaker on the agent loop itself. Without one, a broken tool can trigger an infinite retry loop that burns through your token budget and hits every downstream rate limit simultaneously.

MAX_TOOL_CALLS = 20      # Hard ceiling per conversation turn
MAX_CONSECUTIVE_ERRORS = 3  # Stop if tools keep failing

def run_agent_loop(messages: list, tools: list) -> str:
    tool_call_count = 0
    consecutive_errors = 0
    
    while True:
        if tool_call_count >= MAX_TOOL_CALLS:
            return "I've reached the maximum number of steps for this request. Please try a more specific query."
        
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=4096,
            tools=tools,
            messages=messages
        )
        
        if response.stop_reason == "end_turn":
            return response.content[0].text
        
        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    tool_call_count += 1
                    result = execute_tool_call(block.name, block.input)
                    
                    if result.get("is_error"):
                        consecutive_errors += 1
                    else:
                        consecutive_errors = 0
                    
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result["content"],
                        "is_error": result.get("is_error", False)
                    })
            
            if consecutive_errors >= MAX_CONSECUTIVE_ERRORS:
                return "Multiple consecutive tool failures occurred. The required services may be unavailable."
            
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})

The consecutive_errors counter is what makes this useful — a single error followed by a successful tool call resets the counter. You only abort if you’re in a genuine failure loop.

Bottom Line: What to Implement First

If you’re building a Claude agent that will actually run in production, here’s the priority order for implementing these patterns:

1. Structured tool error responses first — this alone will prevent most agent hallucinations on tool failure and costs almost nothing to implement.
2. Circuit breaker on the agent loop — prevents runaway costs from infinite error loops. Add this before you go live.
3. Retry with backoff for transient failures — the implementation above handles 90% of real-world transient errors.
4. Fallback chains for multi-data-source tools — only worth building once you know which data sources are actually flaky in your stack.

For solo founders and small teams: the first two patterns take about two hours to implement and will prevent the most embarrassing production failures. Start there. The fallback chain pattern is worth adding once you’ve been running in production for a few weeks and can see from your logs which tools actually fail.

For teams building enterprise-grade agents: treat Claude agent error handling as a first-class concern from day one, not a retrofit. Instrument every tool call with structured logging — error type, tool name, input hash, latency. After a week of production traffic, your error patterns will tell you exactly where to invest in fallbacks and smarter retry logic.

The agents that survive contact with production aren’t the ones with the most sophisticated prompts — they’re the ones built by engineers who assumed everything would break and planned accordingly.