Claude API 错误

HTTP 错误

API 遵循可预测的 HTTP 错误代码格式：

• 400 - invalid_request_error：您的请求的格式或内容存在问题。此错误类型也可能用于本节未列出的其他 4XX 状态码。当使用量达到您设置的组织或工作区支出限额时，API 也会返回 400，但 Claude Code 工作区上的限额除外，后者可能会返回 429。

• 401 - authentication_error：您的 API 密钥存在问题（例如，格式错误、已撤销或已过期；请参阅密钥过期）。在 AWS 上的 Claude Platform 上，这也可能表示您的 AWS 凭证或 SigV4 签名存在问题。

• 402 - billing_error：您的账单或付款信息存在问题。请在 Claude Console 中检查您的付款详情，如果您使用的是 AWS 上的 Claude Platform，请在 AWS Marketplace 中检查。

• 403 - permission_error：您的 API 密钥没有使用指定资源的权限。请在 Claude Console 中检查您组织的访问权限和工作区设置。

• 404 - not_found_error：未找到请求的资源。请检查端点路径和请求 URL 中的任何资源 ID。

• 409 - conflict_error：请求与资源的当前状态冲突。例如，资源被并发修改，或者必须唯一的值已被使用。请解决冲突，然后重试请求。

• 413 - request_too_large：请求超过了允许的最大字节数。有关每个端点的最大值，请参阅请求大小限制。

• 429 - rate_limit_error：您的组织已达到速率限制、达到其使用层级的每月支出上限，或达到 Claude Code 工作区的支出限额。层级支出上限的 429 没有 retry-after 标头，并且会持续失败直到访问恢复；有关如何识别它，请参阅达到支出上限。

• 500 - api_error：Anthropic 系统内部发生了意外错误。请使用指数退避重试请求；如果错误持续存在，请联系支持团队并提供请求 ID。

• 504 - timeout_error：请求在处理时超时。对于长时间运行的请求，请考虑使用流式 Messages API。有关更多选项，请参阅长请求。

• 529 - overloaded_error：API 暂时过载。

官方 SDK 会使用指数退避自动重试瞬时故障（例如连接错误、速率限制和 5xx 服务器错误），默认重试两次，并在存在 retry-after 标头时遵循该标头。每个 SDK 客户端都接受一个最大重试次数选项来配置或禁用此行为。

当通过服务器发送事件（SSE）接收流式响应时，错误可能在 API 返回 200 响应之后发生。在这种情况下，错误处理不遵循这些标准机制。有关流中错误的结构，请参阅错误事件。

请求大小限制

API 强制执行请求大小限制：

如果您超过这些限制，您将收到 413 request_too_large 错误。在直接的 Claude API 上，Cloudflare 会在请求到达 API 服务器之前返回此错误。

错误结构

API 始终以 JSON 形式返回错误，其中包含一个顶级 error 对象，该对象始终包含 type 和 message 值。响应还包括一个 request_id 字段，以便于跟踪和调试。例如：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

根据版本控制策略，这些对象中的值可能会扩展，并且 type 值可能会随着时间的推移而增加。

SDK 错误类型

官方 SDK 会为这些错误引发类型化异常，而不是返回原始 JSON，并且类名和命名空间因语言而异。例如，404 在 Python 中显示为 anthropic.NotFoundError，在 Ruby 中显示为 Anthropic::Errors::NotFoundError，在 Java 中显示为 com.anthropic.errors.NotFoundException，在 Go 中显示为单个 *anthropic.Error 值（基于 StatusCode 分支）。请捕获 SDK 的类型化类，而不是对错误消息进行字符串匹配，并首先处理最具体的类。每个 SDK 页面都记录了其完整的异常层次结构：

• Python · TypeScript · C# · Go · Java · PHP · Ruby

请求 ID

每个 API 响应都包含一个唯一的 request-id 标头。此标头包含类似 req_018EeWyXxfu5pfWkrYcMdjWG 的值。相同的标识符在错误响应正文中显示为 request_id 字段。当就特定请求联系支持团队时，请包含此 ID 以帮助快速解决您的问题。

在 AWS 上的 Claude Platform 上，响应包含两个请求 ID：AWS 请求 ID（x-amzn-requestid，主要，在 CloudTrail 中建立索引）和 Anthropic 请求 ID（request-id，次要）。使用 AWS 请求 ID 进行 CloudTrail 查找，使用 Anthropic 请求 ID 处理 Anthropic 支持工单。

Python 和 TypeScript SDK 将请求 ID 作为顶级响应对象上的 _request_id 属性公开。C#、Go、Java 和 PHP SDK 通过其原始响应访问器公开它，Ruby SDK 通过中间件公开它。相同的机制，以及 Python 中的 with_raw_response 和 TypeScript 中的 .withResponse()，也可以读取任何其他响应标头，例如 anthropic-organization-id 和 anthropic-workspace-id。在 AWS 上的 Claude Platform 上，使用原始响应访问器也可以读取 AWS 请求 ID（x-amzn-requestid）：

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

有关其他语言的 AWS 上的 Claude Platform 请求 ID 示例，请参阅请求 ID。

长请求

避免在不使用流式 Messages API 或 Message Batches API 的情况下设置较大的 max_tokens 值：

• 某些网络可能会在可变的时间段后断开空闲连接，这 可能导致请求失败或超时，而无法从 Anthropic 接收响应。
• 网络的可靠性各不相同。Message Batches API 可以帮助您 管理网络问题的风险，它允许您轮询结果，而不需要不间断的网络连接。

如果您正在构建直接的 API 集成，设置 TCP 套接字保活可以减少某些网络上空闲连接超时的影响。

SDK 会验证您的非流式 Messages API 请求预计不会超过 10 分钟的超时。它们还会为 TCP 保活设置套接字选项。

如果您不需要增量处理事件，SDK 可以为您消费流并返回完整的 Message 对象，与非流式调用返回的内容相同：

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

有关更多详细信息，请参阅流式消息。

常见验证错误

不支持预填充

Claude 4.6 及更高版本的模型和 Claude Mythos Preview 不支持预填充助手消息。向这些模型中的任何一个发送带有预填充的最后一条助手消息的请求会返回 400 invalid_request_error：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

请在支持的模型上使用结构化输出、系统提示指令或 output_config.format 代替。

思考块无法修改

如果最近的助手消息包含在发送回 API 之前被编辑、重新排序、过滤掉或重建的 thinking 或 redacted_thinking 块，则请求会返回 400 invalid_request_error。错误消息以有问题的块的位置开头（例如 messages.1.content.0），并包含：

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

在工具使用中，助手回合中的每个 thinking 和 redacted_thinking 块都必须完全按照接收到的样子传回，包括 thinking 字段为空的块。请原封不动地传回思考块，如果您的应用程序在重新发送之前按类型过滤内容块，请同时包含 thinking 和 redacted_thinking。请参阅思考故障排除、保留思考块和保留的思考。

不支持扩展思考

Claude 4.7 及更高版本的模型已移除扩展思考。向这些模型中的任何一个发送 thinking: {"type": "enabled"} 会返回 400 invalid_request_error：

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

请改用自适应思考。迁移到自适应思考显示了参数映射，思考故障排除涵盖了以症状为先的修复方法。

不支持自适应思考

仅支持扩展思考的模型（Claude 4.5 及更早版本的模型）会以 400 invalid_request_error 拒绝 thinking: {"type": "adaptive"}：

adaptive thinking is not supported on this model

请在这些模型上使用 thinking: {"type": "enabled", "budget_tokens": N}；有关配置，请参阅扩展思考，有关以症状为先的修复方法，请参阅思考故障排除。

思考无法禁用

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 上，思考始终开启。向这些模型中的任何一个发送 thinking: {"type": "disabled"} 会返回 400 invalid_request_error：

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5 和 Claude Mythos 5 上，错误消息自身建议的 "thinking.type.enabled" 也会被拒绝。省略 thinking 参数，请求将以自适应思考运行。要在不关闭思考的情况下将思考内容排除在响应之外，请在思考配置上设置 display: "omitted"。请参阅思考故障排除。

不支持强制工具使用

Claude Fable 5.1 和 Claude Mythos 5.1 不支持强制工具使用。向任一模型发送 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."}，包括在令牌计数端点上，会返回 400 invalid_request_error：

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"}（默认值）和 {"type": "none"} 是被接受的。使用 auto 配合严格工具使用以保持工具输入符合模式，或者当您需要响应本身采用固定 JSON 结构时使用结构化输出。请参阅强制工具使用。

思考块不再与对话匹配

在 Claude Fable 5.1 上，只有当 system 提示、tools 和它之前的消息未更改时，API 才接受重放的思考块。对于 2026 年 8 月 31 日或之后创建的新账户，以及任何将 thinking.block_binding.prefix_mismatch_behavior 设置为 "error" 的请求，其较早历史记录已更改的重放块会被以 400 invalid_request_error 拒绝（使用 "drop_block" 时，API 会丢弃该块，请求成功）。消息以第一个失败块的位置开头：

messages.{i}.content.{j}: 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".

如果没有 thinking-binding-controls-2026-08-01 beta 标头，消息还会指明该标头。保持对话历史记录仅追加，或者发送带有 prefix_mismatch_behavior: "drop_block" 的 beta 标头以丢弃该块并继续。来自目标模型无法读取的模型的块会被丢弃而不是拒绝。请参阅保留的思考和思考故障排除。

在没有 thinking-binding-controls-2026-08-01 beta 标头的情况下发送 thinking.block_binding 会返回 400 invalid_request_error，其消息以以下内容结尾：

block_binding: Extra inputs are not permitted

添加标头，或移除该字段。

出站 Web 身份联合已禁用（AWS 上的 Claude Platform）

如果对 AWS 上的 Claude Platform 的每个请求都返回 "Outbound web identity federation is disabled for your account"，请为每个 AWS 账户运行一次 aws iam enable-outbound-web-identity-federation。有关详细信息，请参阅启用出站 Web 身份联合。

后续步骤