Claude API Error Codes Reference: Complete Troubleshooting Guide

The Claude API returns standard HTTP status codes. Some errors are transient and should be retried with backoff. Others indicate a permanent problem in your request that will fail on every retry. Mixing these up is one of the most common — and costly — mistakes in Claude API integration.

This reference covers every error code you'll encounter in production, with the cause, the correct handling strategy, and working Python code for production-grade retry logic. See also the Claude API Enterprise Guide and our breakdown of Claude rate limiting and scaling strategies.

Authentication & Authorisation Errors

Request & Validation Errors

# Correct model identifiers (March 2026)
MODELS = {
    "opus": "claude-opus-4-6",
    "sonnet": "claude-sonnet-4-6",
    "haiku": "claude-haiku-4-5-20251001"
}

# Validate at startup
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

Rate Limit Errors

import anthropic
import time
import random

def call_claude_with_retry(client, max_retries=5, **kwargs):
    """Production retry logic for Claude API calls."""
    for attempt in range(max_retries):
        try:
            return client.messages.create(**kwargs)
        except anthropic.RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Respect retry-after header if present
            retry_after = getattr(e, 'retry_after', None)
            if retry_after:
                wait_time = retry_after
            else:
                # Exponential backoff with jitter
                wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Waiting {wait_time:.1f}s (attempt {attempt+1}/{max_retries})")
            time.sleep(wait_time)
        except anthropic.APIStatusError as e:
            if e.status_code >= 500:
                # Server errors: retry with backoff
                if attempt == max_retries - 1:
                    raise
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
            else:
                # Client errors (400, 401, 403, 404): don't retry
                raise

Server Errors

Content & Context Errors

Error Monitoring in Production

Logging individual errors isn't enough. Production Claude API deployments need error rate monitoring with alerting thresholds. A sudden spike in 5xx errors may indicate an Anthropic outage. A rising baseline of 400 errors may indicate a schema change breaking your request format. A 401 spike may indicate API key rotation that didn't propagate correctly.

Track these metrics as time-series: 429 error rate (rate limit pressure), 5xx error rate (infrastructure health), 400 error rate by error type (request quality), and average response latency with p95 and p99 percentiles. Export them to your existing observability stack — Datadog, Grafana, CloudWatch — using the same patterns as your other API integrations.

import anthropic
from dataclasses import dataclass
from typing import Optional
import logging

logger = logging.getLogger(__name__)

@dataclass
class APICallResult:
    success: bool
    response: Optional[anthropic.types.Message]
    error_type: Optional[str]
    error_code: Optional[int]
    attempt_count: int
    total_latency_ms: float

def tracked_claude_call(client, **kwargs) -> APICallResult:
    """Wrapper that records metrics for every Claude API call."""
    import time
    start = time.monotonic()
    attempts = 0

    try:
        response = call_claude_with_retry(client, **kwargs)
        latency = (time.monotonic() - start) * 1000
        # Emit to your metrics system here
        return APICallResult(True, response, None, None, attempts, latency)
    except anthropic.APIStatusError as e:
        latency = (time.monotonic() - start) * 1000
        logger.error(f"Claude API error: {e.status_code} {e.message}")
        # Alert if error_rate > threshold
        return APICallResult(False, None, type(e).__name__, e.status_code, attempts, latency)

Quick Reference: Error Code Cheatsheet

Print this and put it next to your screen during integration work.

Related Articles