Claude API 错误



HTTP 错误

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

• 400 - invalid_request_error：您的请求格式或内容存在问题。此错误类型也可能用于本节未列出的其他 4XX 状态码。

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

• 402 - billing_error：您的账单或付款信息存在问题。请在 Claude Console 中检查您的付款详情，如果您使用的是 Claude Platform on AWS，请在 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：您的账户已达到速率限制。

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

• 504 - timeout_error：请求在处理过程中超时。对于长时间运行的请求，请考虑使用流式传输 Messages API。请参阅长请求了解更多选项。

• 529 - overloaded_error：API 暂时过载。

  

  当 API 在所有用户中经历高流量时，可能会出现 529 错误。

  在极少数情况下，如果您的组织使用量急剧增加，您可能会因为 API 的加速限制而看到 429 错误。为避免触发加速限制，请逐步增加流量并保持一致的使用模式。

官方 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 以帮助快速解决您的问题。

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

Python 和 TypeScript SDK 在顶级响应对象上以 _request_id 属性的形式公开请求 ID。C#、Go、Java 和 PHP SDK 通过其原始响应访问器公开它，这些访问器还允许您读取任何其他响应标头。在 Claude Platform on AWS 上，也可以使用原始响应访问器读取 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}")

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



长请求

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

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

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

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

如果您不需要增量处理事件，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 Fable 5 和 Claude Mythos 5 上的思考输出。



不支持扩展思考

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



出站 Web 身份联合已禁用（Claude Platform on AWS）

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



后续步骤