Recoverable vs fatal failures — the error classification that stops agent death loops

Your agent crashes. You restart it. It crashes again in the same place. You dig into logs, find a cryptic error, fix what you think is wrong, and restart. Repeat until you give up or accidentally fix it.

This is what happens when you treat all agent failures the same way. But agent failures fall into two categories: recoverable and fatal. The difference changes how you build error handling.

Recoverable failures are temporary problems your agent can work around:

• API rate limits
• Network timeouts
• File locks
• Temporary service outages
• Context window exceeded

Fatal failures are structural problems that won't fix themselves:

• Invalid API keys
• Missing required files
• Malformed configuration
• Permission denied errors
• Syntax errors in generated code

Here's the error handling scaffold that routes failures correctly:

def handle_agent_error(error, context):
    if is_recoverable(error):
        return retry_with_backoff(error, context)
    else:
        return escalate_to_human(error, context)

def is_recoverable(error):
    recoverable_patterns = [
        "rate limit", "timeout", "temporary", 
        "busy", "locked", "context_length_exceeded"
    ]
    return any(pattern in str(error).lower() 
              for pattern in recoverable_patterns)

The key insight: recoverable failures get retry logic, fatal failures get escalation paths. Don't make your agent retry a bad API key for 20 minutes. Don't make it escalate a temporary network hiccup.

Most agent frameworks dump everything into generic try-catch blocks. That's why your agent either gives up too early or loops forever on unfixable problems.

Build your error classifier first, then your retry logic. The classifier determines whether the agent keeps trying or calls for help.

For coding agents, this pattern is critical. A syntax error in generated code is fatal — retry won't fix bad logic. But a GitHub API rate limit is recoverable — wait 60 seconds and continue.

The scaffold needs three components:

1. Error classification — Pattern matching that sorts recoverable from fatal

2. Retry logic with backoff — Exponential delays for recoverable failures

3. Escalation paths — Clean handoff to humans for fatal failures

Your error messages should tell you which path the agent took:

RECOVERABLE: Rate limit hit, retrying in 60s (attempt 2/5)
FATAL: Invalid API key, escalating to human
RECOVERABLE: Context exceeded, switching to summary mode

This prevents the two most expensive agent failure modes: infinite retry loops on unfixable problems, and premature escalation of temporary issues.

The best part: once you build this scaffold, every new agent gets structured error handling by default. No more debugging mystery crashes or watching agents burn API credits on hopeless retries.