/claude-api

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
• An anthropic-beta value that does not exist or is not enabled for your organization. Both cases return the same message: Unexpected value(s) `<value>` for the `anthropic-beta` header.

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:

• The credential's organization or workspace is not allowed to perform this operation.
• The request was blocked by an access requirement, such as a region restriction or identity verification, for a model your organization can otherwise use. The message says what to do.
• Rarely, the model server denies a request that passed the API's access check. The message is Access to this model requires an access grant your request does not have.

A model your organization cannot use is normally a 404, not a 403 (see below). A beta header your organization is not enabled for is a 400.

Fix: Check your organization's access and workspace settings in the Console.

404 Not Found

Causes:

• Typo in model ID (e.g., claude-sonnet-4.6 instead of claude-sonnet-4-6)
• Using deprecated model ID
• A model ID that exists but is not available to your organization
• Invalid API endpoint

A model that does not exist and a model your organization cannot use return the same response, not_found_error with a message that starts with model: <id>. The API does not reveal whether a model exists to callers who cannot use it.

Fix: Use exact model IDs from the models documentation. You can use aliases (e.g., claude-opus-5-5). To see which models your organization can use, call GET /v1/models.

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 Claude Opus 5.5 / Claude Opus 5 / Fable 5/5.1 / 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.
• Claude Opus 5: thinking: {type: "disabled"} returns 400 when effort is xhigh or max - it is accepted at high or below. Thinking is on by default, so omitting the param runs adaptive rather than disabling it.
• Fable 5/5.1 only: an explicit thinking: {type: "disabled"} returns 400 at any effort (it is accepted on Opus 4.8/4.7). Omit the thinking param entirely instead.
• Fable 5/5.1, Mythos 5/5.1: if the organization or workspace is set to zero data retention (ZDR) - or any retention below the required 30 days - then all requests to these models return 400 invalid_request_error ("In order to access this model, your organization or workspace must have data retention enabled."), even with a perfectly valid payload; ZDR only if expressly authorized by Anthropic. Check the retention configuration before debugging the request body.
• Claude Opus 5.5: thinking: {type: "disabled"} or {type: "enabled", budget_tokens: N} returns 400 "thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ("thinking.type.enabled" for the budget form) at every effort level - omit thinking and lower output_config.effort instead. A tools entry of type computer_20251124 returns 400 'claude-opus-5-5' does not support tool types: computer_20251124. followed by Did you mean one of and the accepted types - declare {type: "computer_toolset_20260801"} instead (no beta header, no name / display size). See shared/model-migration.md -> Migrating to Claude Opus 5.5.
• Claude Fable 5.1 / Claude Mythos 5.1 / Claude Opus 5.5 / Claude Sonnet 5.5: tool_choice: {type: "any"} or {type: "tool", name: ...} returns 400 tool_choice: type "tool" and "any" are not supported for this model. - also on count_tokens and Batches. Use {type: "auto"} plus a prompt instruction (strict: true for schema-valid arguments), or structured outputs.
• Claude Sonnet 5.5: thinking: {type: "disabled"} returns 400 "thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. - send {type: "between_tools"} to turn thinking off, or leave thinking on at a lower effort. between_tools has its own 400s: at effort xhigh / max (output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.), with display, budget_tokens, or block_binding beside it, on a per-message effort change (messages.N: output_config.effort 'low' differs from the 'high' in effect before it; ...), and on any other model ("thinking.type.between_tools" is not supported for this model.). On the Claude API and Google Cloud a computer_20251124 tool returns 400 'claude-sonnet-5-5' does not support tool types: computer_20251124. - declare {type: "computer_toolset_20260801"} (Amazon Bedrock still accepts the earlier tool). An advisor tool model of Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, or Sonnet 4.6 returns 400 with a Claude Sonnet 5.5 executor. The history-editing check in the next bullet also applies to Claude Sonnet 5.5 thinking blocks - enforced by default for new accounts on the Claude API and Amazon Bedrock - and block_binding is accepted only with thinking on. See shared/model-migration.md -> Migrating to Claude Sonnet 5.5.
• Claude Fable 5.1 / Claude Opus 5.5 - preserved thinking / history-editing check (new accounts created on/after 2026-08-31 on every platform, or any request that sets prefix_mismatch_behavior; Claude Mythos 5.1 doesn't run it): messages.N.content.M: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". (plus a sentence naming the beta header when it wasn't sent, and optionally one naming the first message that changed) means the system prompt, tool list, or an earlier message changed since that thinking block was produced. Retrying the same body never clears it; count_tokens returns the same 400. (In the Message Batches API the unset default drops the failing blocks instead of failing the item - a Batches item fails as errored only with prefix_mismatch_behavior: "error" set.) Strip the named block and every thinking block after it and retry once, or resend with thinking.block_binding.prefix_mismatch_behavior: "drop_block" under beta thinking-binding-controls-2026-08-01 (the beta is available on the Claude API, Claude Platform on AWS, Bedrock, and Vertex; Foundry unconfirmed - shared/platform-availability.md; without the header that field is a 400 ending block_binding: Extra inputs are not permitted); then fix the harness so it stops editing history (see shared/model-migration.md -> Migrating to Claude Fable 5.1 from Claude Fable 5). The same leading clause with no "bound to a different conversation" sentence is a tampered signature - always a 400, regardless of the setting.

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 status code maps to a specific exception class per SDK.

Exception class names by language

The Ruby and PHP classes live in a dedicated errors namespace - write Anthropic::Errors::RateLimitError and Anthropic\Core\Exceptions\RateLimitException (not bare Anthropic::RateLimitError). All 4xx C# exceptions also inherit from Anthropic4xxException.

Catch most-specific first, in a chain

Order catch/except/rescue clauses from the most specific subclass to the base class, with a separate clause for each category you handle differently - retryable (429, >=500, network) vs. non-retryable (4xx). The SDK defines a distinct class per status for exactly this reason; a single broad catch-all discards that information.

try:
    msg = client.messages.create(...)
except anthropic.NotFoundError as e:          # 404 - e.g. bad model ID
    ...
except anthropic.RateLimitError as e:         # 429 - back off and retry
    ...
except anthropic.APIStatusError as e:         # any other non-2xx HTTP response
    print(e.status_code, e.message)
except anthropic.APIConnectionError as e:     # network failure before a response
    ...

The same chain shape applies in every SDK: TypeScript instanceof Anthropic.NotFoundError -> RateLimitError -> APIConnectionError -> APIError (check APIConnectionError before APIError - in the TypeScript SDK it's a subclass of APIError, unlike Python where it's a sibling); Ruby rescue Anthropic::Errors::NotFoundError -> ...::RateLimitError -> ...::APIStatusError; Java catch (NotFoundException) ... catch (RateLimitException) ... catch (AnthropicServiceException); C# catch (AnthropicNotFoundException) ... catch (AnthropicRateLimitException) ... catch (AnthropicApiException); PHP catch (NotFoundException) ... catch (RateLimitException) ... catch (APIStatusException).

Go - errors.As then branch on status

The Go SDK returns a single *anthropic.Error for all non-2xx responses. Unwrap it with errors.As, then branch on StatusCode:

_, err := client.Messages.New(ctx, params)
if err != nil {
    var apierr *anthropic.Error
    if errors.As(err, &apierr) {
        switch apierr.StatusCode {
        case 404:
            // bad model ID / resource
        case 429:
            // back off and retry
        default:
            // other API error - apierr.StatusCode, apierr.RequestID
        }
    } else {
        // transport-level error (*url.Error wrapping *net.OpError, etc.)
    }
}

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 to classify errors by type name instead of by status code. "billing_error" is a 402 and "permission_error" is a 403.

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