错误

​

HTTP 错误

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

• 400 - invalid_request_error：您的请求格式或内容存在问题。我们也可能使用此错误类型表示下面未列出的其他 4XX 状态码。

• 401 - authentication_error：您的 API 密钥存在问题。

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

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

• 413 - request_too_large：请求超过了允许的最大字节数。

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

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

• 529 - overloaded_error：Anthropic 的 API 暂时过载。

  当 Anthropic API 在所有用户中经历高流量时，可能会发生 529 错误。在极少数情况下，如果您的组织使用量急剧增加，您可能会看到这种类型的错误。 为避免 529 错误，请逐步增加您的流量并保持一致的使用模式。

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

​

错误形式

错误始终以 JSON 形式返回，顶层有一个 error 对象，该对象始终包含 type 和 message 值。例如：

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

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

​

请求 ID

每个 API 响应都包含一个唯一的 request-id 头部。此头部包含一个值，如 req_018EeWyXxfu5pfWkrYcMdjWG。当就特定请求联系支持团队时，请包含此 ID 以帮助我们快速解决您的问题。

我们的官方 SDK 在顶层响应对象上提供此值作为属性，包含 request-id 头部的值：

import anthropic

client = anthropic.Anthropic()

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

​

长请求

我们不建议在不使用我们的流式消息 API或消息批处理 API的情况下设置大的 max_tokens 值：

• 某些网络可能会在一段时间后断开空闲连接，这可能导致请求失败或超时而没有收到来自 Anthropic 的响应。
• 网络的可靠性各不相同；我们的消息批处理 API可以帮助您管理网络问题的风险，允许您轮询结果而不是要求不间断的网络连接。

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

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