[
  {
    "provider": "anthropic",
    "http_status": 400,
    "type": "invalid_request_error",
    "code": null,
    "message_semantics": "Malformed/invalid request; also used for other 4xx not listed, org/workspace spend limit reached, invalid anthropic-version or anthropic-beta value, unsupported parameter for the model.",
    "retryable": false,
    "recommended_action": "Fix the request (message names the field, e.g. 'max_tokens: Field required'). Do not retry unchanged.",
    "status": [
      "DOCUMENTED",
      "LIVE_VERIFIED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors",
    "live_messages": [
      "max_tokens: Field required",
      "max_tokens: 1000000 > 64000, which is the maximum allowed number of output tokens for claude-haiku-4-5-20251001",
      "temperature: range: 0..1",
      "top_k: Input should be a valid integer",
      "`temperature` and `top_p` cannot both be specified for this model. Please use only one.",
      "messages: at least one message is required",
      "The request body is not valid JSON: …",
      "anthropic-version: \"2020-01-01\" is not a valid version",
      "anthropic-version: \"2023-01-01\" not allowed for this endpoint",
      "Unexpected value(s) `…` for the `anthropic-beta` header. …",
      "This model does not support assistant message prefill. The conversation must end with a user message.",
      "adaptive thinking is not supported on this model",
      "messages.2: `tool_use` ids were found without `tool_result` blocks immediately after: … Each `tool_use` block must have a corresponding `tool_result` block in the next message.",
      "Server tools are not supported in the count_tokens endpoint: web_search_20250305. Use the /v1/messages endpoint instead.",
      "'claude-haiku-4-5-20251001' does not support inference_geo.",
      "'claude-haiku-4-5-20251001' does not support the `speed` parameter. This feature is only available on supported models.",
      "betas: Extra inputs are not permitted",
      "output_format: Extra inputs are not permitted",
      "The /v1/complete endpoint has been deprecated. Please use the /v1/messages endpoint instead. See https://platform.claude.com/docs/en/api/messages for details."
    ],
    "response_headers": {
      "x-should-retry": "false"
    }
  },
  {
    "provider": "anthropic",
    "http_status": 401,
    "type": "authentication_error",
    "code": null,
    "message_semantics": "API key malformed, revoked, expired (or bad AWS SigV4 on Claude Platform on AWS).",
    "retryable": false,
    "recommended_action": "Check the key / auth header. Live: 'invalid x-api-key'; anthropic-organization-id header absent on 401.",
    "status": [
      "DOCUMENTED",
      "LIVE_VERIFIED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 402,
    "type": "billing_error",
    "code": null,
    "message_semantics": "Billing/payment problem.",
    "retryable": false,
    "recommended_action": "Fix payment details in Console (or AWS Marketplace).",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 403,
    "type": "permission_error",
    "code": null,
    "message_semantics": "Key lacks permission for the resource (workspace/org settings).",
    "retryable": false,
    "recommended_action": "Check organization access / workspace settings. Does NOT mean the endpoint doesn't exist.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 404,
    "type": "not_found_error",
    "code": null,
    "message_semantics": "Resource not found: unknown path, unknown resource id, or unknown model ('model: <id>').",
    "retryable": false,
    "recommended_action": "Check path/ids; for models, use GET /v1/models.",
    "status": [
      "DOCUMENTED",
      "LIVE_VERIFIED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 409,
    "type": "conflict_error",
    "code": null,
    "message_semantics": "Request conflicts with resource state (concurrent modification, uniqueness).",
    "retryable": true,
    "recommended_action": "Resolve the conflict then retry (SDKs retry 409 by default).",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 413,
    "type": "request_too_large",
    "code": null,
    "message_semantics": "Body exceeds the size limit: Messages & count_tokens 32 MB, Batches 256 MB, Files 500 MB (returned by Cloudflare before the API).",
    "retryable": false,
    "recommended_action": "Shrink the request (use Files API / batches).",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 422,
    "type": "unprocessable_entity (SDK class only)",
    "code": null,
    "message_semantics": "Not in the HTTP error list of the docs; SDKs map 422 to UnprocessableEntityError.",
    "retryable": false,
    "recommended_action": "Treat like 400.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 429,
    "type": "rate_limit_error",
    "code": null,
    "message_semantics": "Rate limit (RPM/ITPM/OTPM), monthly tier spend cap (no retry-after header, keeps failing), acceleration limit, or Claude Code workspace spend limit.",
    "retryable": true,
    "recommended_action": "Honor `retry-after` when present, exponential backoff with jitter; if no retry-after and message mentions spend cap, stop retrying and raise the cap. Ramp traffic gradually.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors",
    "response_headers": [
      "retry-after",
      "anthropic-ratelimit-*"
    ]
  },
  {
    "provider": "anthropic",
    "http_status": 500,
    "type": "api_error",
    "code": null,
    "message_semantics": "Unexpected internal error.",
    "retryable": true,
    "recommended_action": "Retry with exponential backoff; if persistent, contact support with request_id.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 504,
    "type": "timeout_error",
    "code": null,
    "message_semantics": "Request timed out while processing.",
    "retryable": true,
    "recommended_action": "Use streaming or the Batches API for long requests; retry.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 529,
    "type": "overloaded_error",
    "code": null,
    "message_semantics": "API temporarily overloaded (all users); can also arrive as a mid-stream `error` event after HTTP 200.",
    "retryable": true,
    "recommended_action": "Retry with backoff; Priority Tier reduces occurrence. Handle the SSE `error` event.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": null,
    "type": "streaming error event",
    "code": null,
    "message_semantics": "After HTTP 200 the stream may emit `event: error` with {type: error, error:{type, message}} (e.g. overloaded_error).",
    "retryable": true,
    "recommended_action": "Abort the stream, then retry (SDKs raise; Claude 4.6+: resume by sending partial text in a user message asking to continue).",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/build-with-claude/streaming"
  },
  {
    "provider": "anthropic",
    "http_status": null,
    "type": "x-should-retry header",
    "code": null,
    "message_semantics": "Observed on every error response: `x-should-retry: false` for 4xx; SDKs consult this header (true/false) before their status-based retry decision.",
    "retryable": null,
    "recommended_action": "Respect it when present.",
    "status": [
      "LIVE_DISCOVERED"
    ],
    "source": "https://platform.claude.com/docs/en/api/errors"
  },
  {
    "provider": "anthropic",
    "http_status": 200,
    "type": "stop_reason: refusal",
    "code": null,
    "message_semantics": "Not an error: safety classifiers stopped generation; HTTP 200 with stop_details.category.",
    "retryable": false,
    "recommended_action": "Retry on a fallback model (server-side `fallbacks` beta or client-side), redeem fallback_credit_token.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons"
  },
  {
    "provider": "anthropic",
    "http_status": null,
    "type": "tool result error codes",
    "code": null,
    "message_semantics": "Server-tool result blocks carry `error_code` instead of HTTP errors: web_search invalid_tool_input|unavailable|max_uses_exceeded|too_many_requests|query_too_long|request_too_large; web_fetch invalid_tool_input|url_too_long|url_not_allowed|url_not_in_prior_context|url_not_accessible|unsupported_content_type|too_many_requests|max_uses_exceeded|unavailable|content_too_large; code_execution invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded (+output_file_too_large bash, +file_not_found text_editor).",
    "retryable": null,
    "recommended_action": "Inspect the result block; `too_many_requests`/`unavailable` are transient.",
    "status": [
      "DOCUMENTED"
    ],
    "source": "https://platform.claude.com/docs/en/api/messages"
  },
  {
    "provider": "anthropic",
    "http_status": null,
    "type": "SDK retry policy",
    "code": null,
    "message_semantics": "Official SDKs retry connection errors, 408, 409, 429 and >=500 twice by default with exponential backoff (Python: 0.5s initial → 8s max, jitter) honoring retry-after; non-streaming requests time out after 10 min (TS scales up to 60 min by max_tokens/128000 and refuses non-streaming requests expected >10 min: 'Streaming is required for operations that may take longer than 10 minutes').",
    "retryable": null,
    "recommended_action": "Configure max_retries / timeout; stream for large max_tokens.",
    "status": [
      "DOCUMENTED",
      "LIVE_VERIFIED"
    ],
    "source": "https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python",
    "verification_note": "constants read from installed anthropic 1.7.0 and @anthropic-ai/sdk 0.126.0"
  }
]