# Anthropic API errors — catalogue, retry matrix, robust handlers

Status: DOCUMENTED; 400/401/404 shapes and messages LIVE_VERIFIED 2026-09-18 (15 deliberate errors on claude-haiku-4-5-20251001, nothing billed; raws tmp-live/anthropic-core/i*_*.json). x-should-retry header LIVE_DISCOVERED. Sources: https://platform.claude.com/docs/en/api/errors · https://platform.claude.com/docs/en/build-with-claude/streaming#error-events · https://platform.claude.com/docs/en/api/rate-limits · https://platform.claude.com/docs/en/api/beta-headers#error-handling · SDK pages (…/sdks/python#handling-errors etc.) Machine-readable: generated/fragments/errors/anthropic-errors.json Last verified: 2026-09-18

# Error shape

{"type": "error", "error": {"type": "not_found_error", "message": "model: claude-does-not-exist"}, "request_id": "req_011CfBxeBpDojVzndwYnobEw"}

Always JSON; error.type/error.message always present; request_id mirrors the request-id header (quote it to support). Enum of error.type may grow (versioning policy). Mid-stream errors (event: error) have the same error object but no request_id.

# Catalogue + retry matrix

Documented validation families (400): prefill unsupported (Claude 4.6+, Mythos Preview); thinking blocks modified (messages.i.content.j: … cannot be modified); thinking.type.enabled unsupported on Claude 4.7+ ("Use thinking.type.adaptive and output_config.effort"); adaptive unsupported on ≤4.5; disabled unsupported on Fable 5.x / Mythos 5.x / Mythos Preview; forced tool_choice any/tool unsupported on Fable 5.1 / Mythos 5.1; thinking block bound to another conversation (Invalid signature in thinking block…, thinking-binding-controls-2026-08-01); block_binding: Extra inputs are not permitted without that header; AWS "Outbound web identity federation is disabled for your account".

Server-tool failures are not HTTP errors: result blocks carry error_code (web_search: invalid_tool_input|unavailable|max_uses_exceeded|too_many_requests|query_too_long|request_too_large; web_fetch adds url_too_long|url_not_allowed|url_not_in_prior_context|url_not_accessible|unsupported_content_type|content_too_large; code execution: execution_time_exceeded, output_file_too_large, file_not_found). Treat too_many_requests/unavailable as transient.

# Response headers on errors

request-id (always), x-should-retry: false (every 4xx observed; SDKs honor true/false), anthropic-organization-id (absent on 401 and unknown-path 404), retry-after (429/529 when applicable), CF-RAY. Rate-limit buckets are not sent on error responses.

# SDK defaults

Retries: 2, exponential backoff (Python 0.5 s → 8 s, jitter), on connection errors, 408, 409, 429, ≥500, timeouts; retry-after honored. Timeout 10 min; non-streaming requests expected to exceed it are refused (ValueError / AnthropicError("Streaming is required…")). Typed classes: Python anthropic.NotFoundError etc.; TS Anthropic.NotFoundError; Ruby Anthropic::Errors::NotFoundError; Java com.anthropic.errors.NotFoundException; C# AnthropicNotFoundException; Go *anthropic.Error (branch on StatusCode). Catch the most specific class first; never string-match messages.

# Robust handler — Python (examples/shared/errors/anthropic_error_handling.py, LIVE_VERIFIED)

import random, time, anthropic
client = anthropic.Anthropic(max_retries=0)  # we do our own retry here; default 2 is fine in production
FATAL = (anthropic.BadRequestError, anthropic.AuthenticationError, anthropic.PermissionDeniedError,
         anthropic.NotFoundError, anthropic.UnprocessableEntityError)

def call_with_backoff(fn, attempts=4, base=0.5, cap=8.0):
    for i in range(attempts):
        try:
            return fn()
        except anthropic.APIStatusError as e:                       # 4xx/5xx with parsed body
            if isinstance(e, FATAL) or e.response.headers.get("x-should-retry") == "false" or i == attempts - 1:
                raise                                               # log e.status_code, e.request_id, e.body["error"]
            ra = e.response.headers.get("retry-after")
            time.sleep(float(ra) if ra else min(cap, base * 2 ** i) * (1 + random.random() / 4))
        except (anthropic.APIConnectionError, anthropic.APITimeoutError):
            if i == attempts - 1: raise
            time.sleep(min(cap, base * 2 ** i))

msg = call_with_backoff(lambda: client.messages.create(model="claude-haiku-4-5-20251001", max_tokens=16,
                                                       messages=[{"role": "user", "content": "Reply with OK."}]))
if msg.stop_reason == "refusal":  # HTTP 200 but no usable answer
    ...  # retry on a fallback model, read msg.stop_details.category

Streaming: wrap the with client.messages.stream(...) block in the same handler — a mid-stream error event raises anthropic.APIError; retry the whole request. Note: anthropic 1.7.0 dropped temperature/top_p/top_k kwargs — use extra_body.

# Robust handler — TypeScript (examples/shared/errors/anthropic_error_handling.ts, LIVE_VERIFIED)

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ maxRetries: 0 });
const fatal = (e: Anthropic.APIError) => e instanceof Anthropic.BadRequestError || e instanceof Anthropic.AuthenticationError ||
  e instanceof Anthropic.PermissionDeniedError || e instanceof Anthropic.NotFoundError || e instanceof Anthropic.UnprocessableEntityError;

async function withBackoff<T>(fn: () => Promise<T>, attempts = 4, base = 500, cap = 8000): Promise<T> {
  for (let i = 0; ; i++) {
    try { return await fn(); }
    catch (e) {
      if (!(e instanceof Anthropic.APIError)) throw e;                       // APIConnectionError etc. also extend APIError
      if (fatal(e) || e.headers?.get?.("x-should-retry") === "false" || i === attempts - 1) throw e; // e.status, e.requestID, e.error
      const ra = e.headers?.get?.("retry-after");
      await new Promise(r => setTimeout(r, ra ? Number(ra) * 1000 : Math.min(cap, base * 2 ** i) * (1 + Math.random() / 4)));
    }
  }
}
const msg = await withBackoff(() => client.messages.create({ model: "claude-haiku-4-5-20251001", max_tokens: 16, messages: [{ role: "user", content: "Reply with OK." }] }));
if (msg.stop_reason === "refusal") { /* fallback model; msg.stop_details?.category */ }

For client.messages.stream(), attach .on("error", …) and/or await finalMessage() inside the same wrapper.

# Errors vs stop reasons

Errors = HTTP 4xx/5xx (or SSE error event), no usable content. Stop reasons = HTTP 200 with content and a stop_reason (refusal, max_tokens, pause_turn need application handling) — see docs/anthropic/stop-reasons.md.