Data: HTTP error codes reference

HTTP Error Codes Reference

This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the python/ or typescript/ folders.

Error Code Summary

Detailed Error Information

400 Bad Request

Causes:

• Malformed JSON in request body
• Missing required parameters (model, max_tokens, messages)
• Invalid parameter types (e.g., string where integer expected)
• Empty messages array
• Messages not alternating user/assistant

Example error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Fix: Validate request structure before sending. Check that:

• model is a valid model ID
• max_tokens is a positive integer
• messages array is non-empty and alternates correctly

401 Unauthorized

Causes:

• Missing x-api-key header or Authorization header
• Invalid API key format
• Revoked or deleted API key
• OAuth bearer token sent via x-api-key instead of Authorization: Bearer
• Both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set — the SDK sends both headers and the API rejects the request

Fix: Set ANTHROPIC_API_KEY, or run ant auth login and leave the client constructor empty. For raw HTTP with an OAuth token, use Authorization: Bearer <token> (not x-api-key:).

403 Forbidden

Causes:

• API key doesn't have access to the requested model
• Organization-level restrictions
• Attempting to access beta features without beta access

Fix: Check your API key permissions in the Console. You may need a different API key or to request access to specific features.

404 Not Found

Causes:

• Typo in model ID (e.g., claude-sonnet-4.6 instead of claude-sonnet-4-6)
• Using deprecated model ID
• Invalid API endpoint

Fix: Use exact model IDs from the models documentation. You can use aliases (e.g., {{OPUS_ID}}).

413 Request Too Large

Causes:

• Request body exceeds maximum size
• Too many tokens in input
• Image data too large

Fix: Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.

400 Validation Errors

Some 400 errors are specifically related to parameter validation:

• max_tokens exceeds model's limit
• Invalid temperature value (must be 0.0-1.0)
• budget_tokens >= max_tokens in extended thinking
• Invalid tool definition schema

Model-specific 400s on Opus 4.8 / 4.7:

• temperature, top_p, top_k are removed — sending any of them returns 400. Delete the parameter; see shared/model-migration.md → Per-SDK Syntax Reference.
• thinking: {type: "enabled", budget_tokens: N} is removed — sending it returns 400. Use thinking: {type: "adaptive"} instead.

Common mistake with extended thinking on older models (Opus 4.6 and earlier):

# Wrong: budget_tokens must be < max_tokens
thinking: budget_tokens=10000, max_tokens=1000  → Error!

# Correct
thinking: budget_tokens=10000, max_tokens=16000

429 Rate Limited

Causes:

• Exceeded requests per minute (RPM)
• Exceeded tokens per minute (TPM)
• Exceeded tokens per day (TPD)

Headers to check:

• retry-after: Seconds to wait before retrying
• x-ratelimit-limit-*: Your limits
• x-ratelimit-remaining-*: Remaining quota

Fix: The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: max_retries=2). For custom retry behavior, see the language-specific error handling examples.

500 Internal Server Error

Causes:

• Temporary Anthropic service issue
• Bug in API processing

Fix: Retry with exponential backoff. If persistent, check status.anthropic.com.

529 Overloaded

Causes:

• High API demand
• Service capacity reached

Fix: Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.

Common Mistakes and Fixes

Typed Exceptions in SDKs

Always use the SDK's typed exception classes instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:

// ✅ Correct: use typed exceptions
try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // Handle rate limiting
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API error ${error.status}:`, error.message);
  }
}

// ❌ Wrong: don't check error messages with string matching
try {
  const response = await client.messages.create({...});
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);
  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
}

All exception classes extend Anthropic.APIError, which has a status property. Use instanceof checks from most specific to least specific (e.g., check RateLimitError before APIError).

Error .type Field

All APIStatusError subclasses now expose a .type property (Python: .type, TypeScript: .type, Java: .errorType(), Go: .Type(), Ruby: .type, PHP: .type) that returns the API error type string (e.g., "invalid_request_error", "authentication_error", "rate_limit_error", "overloaded_error"). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing "billing_error" from "permission_error" (both map to 403).

except anthropic.APIStatusError as e:
    if e.type == "rate_limit_error":
        # handle rate limiting
    elif e.type == "overloaded_error":
        # handle overload