Originally published at claudeguide.io/claude-api-error-codes-reference

Claude API Error Codes Reference: 400, 401, 429, 529 and How to Fix Them

The Claude API returns standard HTTP status codes for errors: 400 (bad request), 401 (invalid API key), 403 (forbidden), 404 (not found), 422 (unprocessable), 429 (rate limit), 500 (server error), and 529 (overloaded). The 529 overloaded error is unique to Anthropic and means the API is at capacity — retry with exponential backoff. This reference covers every error code, its exact JSON body, common causes, and fix strategies.

Understanding these codes reduces integration debugging time significantly. Error codes are consistent across the Python SDK, TypeScript SDK, and raw HTTP requests.

Quick Reference Table

400 Bad Request

Cause: The request body is malformed, missing required fields, or contains invalid JSON.

Response body:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: field required"
  }
}

Common triggers:

• Missing messages array
• Missing model field
• max_tokens set to 0 or a negative number
• messages array is empty ([])
• Sending content: null instead of content: ""
• Wrong role value (must be "user" or "assistant")

Fix:

# Wrong — missing max_tokens
response = client.messages.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "hello"}]
    # max_tokens is required!
)

# Correct
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hello"}]
)

401 Unauthorized

Cause: The API key is missing, malformed, or revoked.

Response body:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

Common triggers:

• x-api-key header not set
• API key contains extra spaces or newlines (common when copying from dashboards)
• API key was revoked in the Anthropic console
• Using Authorization: Bearer ... instead of x-api-key: ...

Fix:

import os

# Wrong — using wrong header name
headers = {"Authorization": f"Bearer {api_key}"}

# Correct
headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}

The Python and TypeScript SDKs handle headers automatically — 401s via the SDK almost always mean the ANTHROPIC_API_KEY environment variable is not set or is incorrect.

403 Forbidden

Cause: The API key exists but does not have permission for the requested model or feature.

Response body:

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have access to this model"
  }
}

Common triggers:

• Requesting Claude Opus before your account has Opus access
• Accessing a feature still in limited beta
• Organization-level restrictions set by an admin

Fix: Check your model access in the Anthropic console. Downgrade to claude-sonnet-4-5 or claude-haiku-4-5 if Opus access is not enabled.

404 Not Found

Cause: The endpoint URL is wrong.

Response body:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not Found"
  }
}

Correct endpoint: https://api.anthropic.com/v1/messages

Common triggers:

• Extra or missing path segments (/v1/message vs /v1/messages)
• Trying to call an OpenAI-style endpoint (/v1/chat/completions) — the Claude API uses /v1/messages

422 Unprocessable Entity

Cause: The request is syntactically valid but contains logically invalid parameters.

Response body:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: must be less than or equal to 8192 for claude-haiku-4-5"
  }
}

Common triggers:

• max_tokens exceeds the model's maximum output limit
• Invalid temperature value (must be 0.0–1.0)
• top_p and temperature both set (mutually exclusive)
• Tool definition missing required fields (name, description, input_schema)

429 Rate Limited

Cause: Too many API requests within the rate limit window.

Response body:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after 60 seconds."
  }
}

The response includes a Retry-After header with seconds to wait.

Rate limits (as of April 2026):

• Free tier: 5 requests/minute, 25,000 tokens/minute
• Build tier: 50 requests/minute, 100,000 tokens/minute
• Scale tier: Custom limits

Retry strategy:

import time
import anthropic

client = anthropic.Anthropic()

def call_with_retry(prompt: str, max_retries: int = 5) -

[→ Get Claude Cost Optimization Toolkit — $59](https://shoutfirst.gumroad.com/l/msjkda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-api-error-codes-reference)

---

## 529 Overloaded — The Anthropic-Specific Error

**Cause:** The Anthropic API is at capacity. This is not a rate limit — your request count is within limits, but the servers are temporarily overloaded.

**Response body:**

json
{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "Overloaded"
}
}

**Key distinction from 429:**
- **429** = you are sending too fast, reduce your rate
- **529** = Anthropic servers are busy, wait and retry regardless of your rate

**529 retry strategy:**

python
import time
import anthropic

def call_with_overload_handling(prompt: str) -

→ Get Claude Cost Optimization Toolkit — $59

30-day money-back guarantee. Instant download.