錯誤



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 金鑰沒有使用指定資源的權限。

• 404 - not_found_error：找不到請求的資源。

• 409 - conflict_error：請求與資源的目前狀態衝突。例如，資源被同時修改，或必須唯一的值已被使用。請解決衝突，然後重試請求。

• 413 - request_too_large：請求超過允許的最大位元組數。請參閱請求大小限制以了解各端點的最大值。

• 429 - rate_limit_error：您的帳戶已達到速率限制。

• 500 - api_error：Anthropic 系統內部發生了非預期的錯誤。

• 504 - timeout_error：請求在處理過程中逾時。對於長時間執行的請求，請考慮使用串流。請參閱長時間請求以了解更多選項。

• 529 - overloaded_error：API 暫時過載。

  

  當 API 在所有使用者間經歷高流量時，可能會發生 529 錯誤。

  在極少數情況下，如果您的組織使用量急劇增加，您可能會因為 API 的加速限制而看到 429 錯誤。為避免觸及加速限制，請逐步增加您的流量並保持一致的使用模式。

官方 SDK 會自動以指數退避（exponential backoff）重試暫時性失敗（例如連線錯誤、速率限制和 5xx 伺服器錯誤），預設重試兩次，並在存在 retry-after 標頭時遵循該標頭。每個 SDK 用戶端都接受最大重試次數選項來設定或停用此行為。

透過伺服器發送事件（server-sent events，SSE）接收串流回應時，錯誤可能在 API 回傳 200 回應之後發生。在這種情況下，錯誤處理不遵循這些標準機制。請參閱錯誤事件以了解串流中途錯誤的格式。



請求大小限制

API 強制執行請求大小限制：

如果您超過這些限制，您將收到 413 request_too_large 錯誤。在直接的 Claude API 上，此錯誤是在請求到達 API 伺服器之前由 Cloudflare 回傳的。



錯誤格式

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 會針對這些錯誤引發型別化例外（typed exceptions），而不是回傳原始 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 透過其原始回應存取器（raw-response accessors）公開它，這些存取器也讓您可以讀取任何其他回應標頭。在 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 設定 socket 選項。

如果您不需要逐步處理事件，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(message.content[0].text)

請參閱串流訊息以了解更多詳細資訊。



常見驗證錯誤



不支援預填

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 不支援預填（prefilling）助理訊息。向這些模型中的任何一個發送帶有預填的最後一則助理訊息的請求，會回傳 400 invalid_request_error：

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

請改為在支援的模型上使用結構化輸出、系統提示指令，或 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 Platform on AWS）

如果對 Claude Platform on AWS 的每個請求都回傳 "Outbound web identity federation is disabled for your account"，請為每個 AWS 帳戶執行一次 aws iam enable-outbound-web-identity-federation。請參閱啟用對外網路身分聯合以了解詳細資訊。



後續步驟