錯誤

​

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 設置套接字選項。