错误



HTTP 错误

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

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

• 401 - authentication_error：您的 API 密钥存在问题。在 AWS 上的 Claude Platform 中，这也可能表示您的 AWS 凭证或 SigV4 签名存在问题。

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

• 403 - permission_error：您的 API 密钥没有使用指定资源的权限。

• 404 - not_found_error：未找到请求的资源。

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

• 429 - rate_limit_error：您的账户已达到速率限制。

• 500 - api_error：Anthropic 系统内部发生了意外错误。

• 504 - timeout_error：请求在处理过程中超时。对于长时间运行的请求，请考虑使用流式传输。

• 529 - overloaded_error：API 暂时过载。

  

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

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

当通过 SSE 接收流式传输响应时，可能会在返回 200 响应后发生错误，在这种情况下，错误处理将不遵循这些标准机制。



请求大小限制

API 强制执行请求大小限制以确保最佳性能：

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



错误结构

错误始终以 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 的值。在就特定请求联系支持团队时，请包含此 ID 以帮助快速解决您的问题。

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

官方 SDK 在顶级响应对象上提供 Anthropic 请求 ID 作为属性，其中包含 request-id 标头的值。在 AWS 上的 Claude Platform 中，使用原始响应访问器还可以从 HTTP 标头中读取 AWS 请求 ID：

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    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 socket keep-alive（TCP 套接字保活）可以减少某些网络上空闲连接超时的影响。

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

如果您不需要增量处理事件，请使用 .stream() 配合 .get_final_message()（Python）或 .finalMessage()（TypeScript）来获取完整的 Message 对象，而无需编写事件处理代码：

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

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



常见验证错误



不支持预填充

Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 不支持预填充助手消息。向这些模型中的任何一个发送带有预填充的最后一条助手消息的请求，将返回 400 invalid_request_error：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

请改用支持该功能的模型上的结构化输出、系统提示指令或 output_config.format。



出站 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 身份联合。