Claude API Error Codes Reference

Claude API Error Codes Reference: 400, 401, 403, 429, 500, 529

When working with the Claude API, understanding error codes is essential for building reliable applications. This reference guide covers every common HTTP error code returned by the Claude API, explains what causes each error, and provides concrete solutions and code examples for handling them.

400 Bad Request

The request body is malformed or contains invalid parameters.

Common causes:

• Invalid JSON syntax in the request body
• Missing required fields (model, max_tokens, or messages)
• Invalid model name or unsupported model version
• Messages array is empty or incorrectly formatted
• max_tokens exceeds the model's maximum output limit

# Example: Missing required field
# Error: {"type":"error","error":{"type":"invalid_request_error","message":"messages: field required"}}

# Fix: Ensure all required fields are present
curl https://claude4u.com/antigravity/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

401 Unauthorized

The API key is missing, invalid, or revoked.

Common causes:

• Missing x-api-key header
• API key has been revoked or deleted
• Using a direct Anthropic key with a relay service or vice versa
• Environment variable not set or not exported

# Verify your key is set
echo $ANTHROPIC_API_KEY

# For relay services, ensure you're using the relay key (cr_ prefix)
export ANTHROPIC_API_KEY="cr_your_relay_key_here"
export ANTHROPIC_BASE_URL="https://claude4u.com/antigravity"

403 Forbidden

The API key is valid but does not have permission for the requested operation.

Common causes:

• Account has not been activated or billing is not set up
• API key does not have access to the requested model
• Regional restrictions on the API key
• Relay service key lacks permission for the requested model tier

429 Too Many Requests (Rate Limited)

You have exceeded the rate limit for your API key or account tier.

Common causes:

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

# Implement exponential backoff in Python
import time
import anthropic

client = anthropic.Anthropic()

def call_with_retry(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=1024,
                messages=messages
            )
        except anthropic.RateLimitError:
            wait_time = 2 ** attempt  # 1, 2, 4, 8, 16 seconds
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
    raise Exception("Max retries exceeded")

500 Internal Server Error

An unexpected error occurred on Anthropic's servers.

What to do:

• Retry the request after a brief delay (1-5 seconds)
• If persistent, check Anthropic's status page for outages
• Ensure your request payload is not unusually large or complex
• Contact Anthropic support if the error persists for more than 30 minutes

529 Overloaded

Anthropic's API is temporarily overloaded and cannot process your request. This is different from 429 (your personal rate limit) — 529 means the overall system is under heavy load.

What to do:

• Retry with exponential backoff starting at 5-10 seconds
• Try a different model (e.g., switch from Opus to Sonnet)
• Use a relay service that automatically routes to available accounts

# Node.js retry with 529 handling
async function callClaude(messages, retries = 5) {
  for (let i = 0; i < retries; i++) {
    try {
      return await client.messages.create({
        model: 'claude-sonnet-4-20250514',
        max_tokens: 1024,
        messages
      });
    } catch (err) {
      if (err.status === 529 || err.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        console.log(`Server busy (${err.status}). Retrying in ${delay}ms...`);
        await new Promise((r) => setTimeout(r, delay));
      } else {
        throw err;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Error Handling Best Practices

1. Always implement retry logic with exponential backoff for 429, 500, and 529 errors.
2. Log error details including the error type, message, and request ID for debugging.
3. Set request timeouts to prevent hanging connections (60-120 seconds for non-streaming).
4. Use a relay service to handle 529 errors automatically through multi-account failover.
5. Monitor error rates and alert when they exceed normal thresholds.
6. Validate requests client-side before sending to catch 400 errors early.

Understanding these error codes and implementing proper handling ensures your Claude API integration is robust and production-ready. A relay service like claude4u.com handles many of these errors automatically through intelligent retry and account pooling.