Error Handling

Building reliable autonomous agents requires robust error handling. This guide covers ClawFirst MCP server error patterns, recovery strategies, and fault tolerance best practices.

Error Response Format

All MCP tool errors follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "context": "Additional information for debugging"
    },
    "retryable": true
  },
  "timestamp": 1709834400000
}

Error Categories

Authentication Errors

INVALID_WALLET

{
  "error": {
    "code": "INVALID_WALLET",
    "message": "Agent wallet keypair invalid or inaccessible",
    "details": {
      "wallet_path": "~/.config/solana/agent.json",
      "reason": "File not found"
    },
    "retryable": false
  }
}

Solution: Verify wallet file path and permissions (chmod 400).

SIGNATURE_FAILED

{
  "error": {
    "code": "SIGNATURE_FAILED",
    "message": "HSM signing operation failed",
    "details": {
      "signing_service": "hsm://production-cluster",
      "reason": "Connection timeout"
    },
    "retryable": true
  }
}

Solution: Check HSM connectivity and credentials. Retry with exponential backoff.

Policy Violation Errors

POLICY_VIOLATION

{
  "error": {
    "code": "POLICY_VIOLATION",
    "message": "Transaction violates approval policy",
    "details": {
      "policy_name": "daily_limit_exceeded",
      "limit": "5000 USDC",
      "current_spend": "4800 USDC",
      "requested_amount": "500 USDC"
    },
    "retryable": false
  }
}

Solution: Adjust transaction amount or update approval policy. Request human approval if configured.

APPROVAL_TIMEOUT

{
  "error": {
    "code": "APPROVAL_TIMEOUT",
    "message": "Human approval not received within timeout period",
    "details": {
      "timeout": "24 hours",
      "approvers": ["[email protected]"],
      "approval_token": "appr_abc123"
    },
    "retryable": true
  }
}

Solution: Re-submit approval request or extend timeout configuration.

Transaction Errors

INSUFFICIENT_BALANCE

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Agent wallet balance insufficient for transaction",
    "details": {
      "required": "0.5 SOL",
      "available": "0.3 SOL",
      "network_fee": "0.000005 SOL"
    },
    "retryable": false
  }
}

Solution: Fund agent wallet with sufficient SOL or USDC.

SESSION_EXPIRED

{
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Payment session TTL exceeded (15 minutes)",
    "details": {
      "session_id": "sess_x4k9j2n8p5",
      "created_at": 1709834400000,
      "expires_at": 1709835300000
    },
    "retryable": true
  }
}

Solution: Re-initialize payment session with x402.initialize_payment.

TRANSACTION_FAILED

{
  "error": {
    "code": "TRANSACTION_FAILED",
    "message": "Blockchain transaction simulation failed",
    "details": {
      "reason": "Insufficient lamports for rent",
      "logs": ["Program log: Error: insufficient funds", "..."],
      "tx_signature": null
    },
    "retryable": false
  }
}

Solution: Review transaction logs and adjust parameters. Ensure account has rent-exempt balance.

Network Errors

NETWORK_ERROR

{
  "error": {
    "code": "NETWORK_ERROR",
    "message": "Failed to connect to Solana RPC endpoint",
    "details": {
      "rpc_endpoint": "https://api.mainnet-beta.solana.com",
      "error_type": "timeout",
      "timeout_ms": 30000
    },
    "retryable": true
  }
}

Solution: Retry with exponential backoff. Check Solana network status.

RPC_ERROR

{
  "error": {
    "code": "RPC_ERROR",
    "message": "Solana RPC returned error",
    "details": {
      "rpc_code": -32005,
      "rpc_message": "Node is behind by 150 slots",
      "endpoint": "https://api.mainnet-beta.solana.com"
    },
    "retryable": true
  }
}

Solution: Wait for RPC node to sync or use alternative RPC endpoint.

Rate Limit Errors

RATE_LIMIT_EXCEEDED

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Transaction rate limit exceeded",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retry_after": 30
    },
    "retryable": true
  }
}

Solution: Implement exponential backoff. Respect retry_after value.

See Rate Limits for detailed quota management.

Agent Error Handling Patterns

Pattern 1: Exponential Backoff with Jitter

import time
import random
from clawfirst import X402Provider, X402Error

async def call_tool_with_retry(
    provider: X402Provider,
    tool_name: str,
    params: dict,
    max_retries: int = 3
):
    for attempt in range(max_retries):
        try:
            result = await provider.call_tool(tool_name, params)
            return result
        except X402Error as e:
            if not e.retryable or attempt >= max_retries - 1:
                raise

            # Exponential backoff with jitter
            backoff = (2 ** attempt) + random.uniform(0, 1)
            await asyncio.sleep(backoff)
            continue

Pattern 2: Circuit Breaker

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, failure_threshold=3, recovery_timeout=60):
        self.failure_count = 0
        self.failure_threshold = failure_threshold
        self.recovery_timeout = timedelta(seconds=recovery_timeout)
        self.last_failure_time = None
        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN

    async def call(self, func, *args, **kwargs):
        if self.state == 'OPEN':
            if datetime.now() - self.last_failure_time > self.recovery_timeout:
                self.state = 'HALF_OPEN'
            else:
                raise Exception('Circuit breaker is OPEN')

        try:
            result = await func(*args, **kwargs)
            if self.state == 'HALF_OPEN':
                self.state = 'CLOSED'
                self.failure_count = 0
            return result
        except Exception as e:
            self.failure_count += 1
            self.last_failure_time = datetime.now()

            if self.failure_count >= self.failure_threshold:
                self.state = 'OPEN'

            raise

# Usage
circuit_breaker = CircuitBreaker()

async def process_payment():
    return await circuit_breaker.call(
        agent.run,
        "Pay invoice #402 for $250"
    )

Pattern 3: Idempotent Retry with Session IDs

import uuid
from clawfirst import X402Provider

class IdempotentAgent:
    def __init__(self, provider: X402Provider):
        self.provider = provider
        self.session_cache = {}

    async def initialize_payment_idempotent(self, amount, recipient, purpose):
        # Generate stable idempotency key from payment intent
        idempotency_key = str(uuid.uuid5(
            uuid.NAMESPACE_DNS,
            f"{amount}-{recipient}-{purpose}"
        ))

        # Check cache
        if idempotency_key in self.session_cache:
            return self.session_cache[idempotency_key]

        # Initialize payment
        try:
            session = await self.provider.call_tool('x402.initialize_payment', {
                'amount': amount,
                'recipient': recipient,
                'purpose': purpose,
                'idempotency_key': idempotency_key
            })

            # Cache session
            self.session_cache[idempotency_key] = session
            return session
        except X402Error as e:
            if e.code == 'SESSION_EXPIRED':
                # Remove from cache and retry
                self.session_cache.pop(idempotency_key, None)
                return await self.initialize_payment_idempotent(amount, recipient, purpose)
            raise

Pattern 4: Fallback Chain

from typing import List, Callable

async def try_with_fallbacks(
    primary_func: Callable,
    fallback_funcs: List[Callable],
    *args,
    **kwargs
):
    """Try primary function, falling back to alternatives on failure."""
    try:
        return await primary_func(*args, **kwargs)
    except X402Error as e:
        if not e.retryable or not fallback_funcs:
            raise

        # Try first fallback
        next_fallback = fallback_funcs[0]
        remaining_fallbacks = fallback_funcs[1:]
        return await try_with_fallbacks(
            next_fallback,
            remaining_fallbacks,
            *args,
            **kwargs
        )

# Usage: Try multiple RPC endpoints
async def submit_transaction(session_id):
    return await try_with_fallbacks(
        lambda: provider.authorize_transaction(session_id, rpc='mainnet'),
        [
            lambda: provider.authorize_transaction(session_id, rpc='quicknode'),
            lambda: provider.authorize_transaction(session_id, rpc='alchemy')
        ]
    )

Error Handling Best Practices

1. Distinguish Retryable vs. Non-Retryable Errors

from clawfirst import X402Error

try:
    result = await agent.run("Pay invoice")
except X402Error as e:
    if e.retryable:
        # Implement retry with backoff
        await retry_with_backoff(agent.run, "Pay invoice")
    else:
        # Log and alert - manual intervention required
        logger.error(f"Non-retryable error: {e.code} - {e.message}")
        alert_team(e)

2. Log Complete Error Context

import logging
import json

logger = logging.getLogger(__name__)

try:
    result = await provider.call_tool('x402.authorize_transaction', params)
except X402Error as e:
    logger.error(
        "Transaction failed",
        extra={
            "error_code": e.code,
            "error_message": e.message,
            "error_details": json.dumps(e.details),
            "session_id": params.get('session_id'),
            "agent_id": "payment_agent",
            "retryable": e.retryable
        }
    )

3. Implement Graceful Degradation

async def process_invoice(invoice):
    try:
        # Primary path: Autonomous payment
        result = await agent.run(f"Pay invoice {invoice.id}")
        return result
    except PolicyViolationError:
        # Fallback: Request human approval
        approval = await request_human_approval(invoice)
        if approval.approved:
            return await agent.run(f"Pay invoice {invoice.id} with approval {approval.token}")
        raise
    except InsufficientBalanceError:
        # Fallback: Alert treasury team
        await alert_treasury_team(f"Insufficient funds for invoice {invoice.id}")
        raise

4. Monitor Error Rates

from prometheus_client import Counter

error_counter = Counter(
    'clawfirst_errors_total',
    'Total errors by code',
    ['error_code', 'retryable']
)

try:
    result = await provider.call_tool(tool_name, params)
except X402Error as e:
    error_counter.labels(
        error_code=e.code,
        retryable=str(e.retryable)
    ).inc()
    raise

5. Set Appropriate Timeouts

import asyncio

async def call_tool_with_timeout(tool_name, params, timeout_seconds=30):
    try:
        return await asyncio.wait_for(
            provider.call_tool(tool_name, params),
            timeout=timeout_seconds
        )
    except asyncio.TimeoutError:
        raise X402Error(
            code='TIMEOUT',
            message=f'Tool call exceeded {timeout_seconds}s timeout',
            retryable=True
        )

Testing Error Scenarios

Simulate Network Failures

# Test network error handling
async def test_network_failure_recovery():
    # Mock network error
    with patch.object(provider, 'call_tool', side_effect=NetworkError()):
        result = await call_tool_with_retry(
            provider,
            'x402.initialize_payment',
            {'amount': '0.1 SOL', 'recipient': '[email protected]'}
        )
    # Verify retry logic executed correctly

Simulate Policy Violations

# Test approval workflow
async def test_approval_required():
    # Request large payment exceeding auto-approve threshold
    result = await agent.run("Pay $10000 to vendor")
    assert result.status == 'pending_approval'
    assert result.requires_human_approval == True

Simulate RPC Failures

# Test RPC failover
async def test_rpc_failover():
    with patch.object(provider, 'primary_rpc', side_effect=RPCError()):
        result = await submit_transaction(session_id)
    # Verify fallback RPC was used
    assert result.rpc_endpoint == 'https://fallback-rpc.com'

Debugging Failed Transactions

Enable Debug Logging

clawfirst serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --log-level debug \
  --log-file /var/log/clawfirst/debug.log

Inspect Transaction Logs

from clawfirst import X402Provider

provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json",
    debug=True  # Enable verbose logging
)

try:
    result = await provider.call_tool('x402.authorize_transaction', params)
except X402Error as e:
    # Transaction logs included in error details
    print("Transaction logs:")
    for log in e.details.get('logs', []):
        print(log)

Query Transaction Status

# Get detailed transaction status
status = await provider.call_tool('x402.verify_settlement', {
    'tx_signature': 'your_tx_signature_here'
})

print(f"Status: {status.settlement_state}")
print(f"Confirmations: {status.confirmations}")
print(f"Error: {status.error}")

Common Error Resolution Workflows

Error	Immediate Action	Long-term Fix
INSUFFICIENT_BALANCE	Fund agent wallet	Implement balance monitoring and auto-funding
POLICY_VIOLATION	Adjust transaction or request approval	Review and update approval policies
SESSION_EXPIRED	Re-initialize payment session	Reduce agent processing time
RATE_LIMIT_EXCEEDED	Wait and retry	Upgrade plan or implement request queuing
NETWORK_ERROR	Retry with backoff	Configure multiple RPC endpoints
SIGNATURE_FAILED	Check HSM connectivity	Implement HSM health monitoring

Getting Help

If you encounter persistent errors:

1. Check Status Page for system incidents

2. Review FAQ for common issues

3. Contact support with:

   • Error code and message

   • Session ID or transaction signature

   • Agent configuration (approval policies, network, etc.)

   • Relevant log excerpts

4. Join Discord community for peer support

Next Steps

• Rate Limits - Transaction throughput and quota management

• MCP Tools - Complete API reference

• Examples - Error handling code samples