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 的 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(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"。請參閱思考疑難排解。



對外網路身分聯合已停用（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。請參閱啟用對外網路身分聯合以了解詳細資訊。



後續步驟