Claude API 錯誤

HTTP 錯誤

API 採用可預期的 HTTP 錯誤碼格式：

• 400 - invalid_request_error：您的請求格式或內容有問題。此錯誤類型也可能用於本節未列出的其他 4XX 狀態碼。當用量達到您為組織或工作區設定的支出限制時，API 也會回傳 400。例外是 Claude Code 工作區上的限制，這類限制可能改為回傳 429。

• 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：您的組織已達到速率限制、已達到其用量層級的每月支出上限，或已達到 Claude Code 工作區的支出限制。因層級支出上限而產生的 429 不含 retry-after 標頭，且在存取恢復前會持續失敗；如何辨識此情況，請參閱達到支出上限。

• 500 - api_error：Anthropic 系統內部發生非預期的錯誤。請以「exponential backoff」（指數退避）方式重試請求；如果錯誤持續發生，請附上請求 ID 聯絡支援團隊。

• 504 - timeout_error：請求在處理期間逾時。對於長時間執行的請求，建議使用串流 Messages API。更多選項請參閱長時間請求。

• 529 - overloaded_error：API 暫時過載。

官方 SDK 會以指數退避方式自動重試暫時性失敗（例如連線錯誤、速率限制與 5xx 伺服器錯誤）。預設會重試兩次，且若回應中有 retry-after 標頭，SDK 會遵循該標頭。SDK 用戶端接受 max_retries，可用來設定或停用此行為。

透過「server-sent events」（伺服器傳送事件），即 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 會以 anthropic.NotFoundError 的形式出現。Go SDK 對所有狀態碼都使用同一個錯誤類型 *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，主要 ID，已在 CloudTrail 中建立索引）與 Anthropic 請求 ID（request-id，次要 ID）。在 CloudTrail 中查詢時請使用 AWS 請求 ID，提交 Anthropic 支援工單時請使用 Anthropic 請求 ID。

Python 與 TypeScript SDK 會在頂層回應物件上以 _request_id 屬性提供請求 ID。C#、Go、Java 與 PHP SDK 透過各自的原始回應存取器提供此 ID，Ruby SDK 則透過中介軟體提供。除了 Ruby 以外，所有 SDK 都可以使用 with_raw_response 讀取其他回應標頭，例如 anthropic-organization-id 與 anthropic-workspace-id。在 Ruby 中，請使用同一個中介軟體。在 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，都不支援「prefill」（預填）助理訊息。如果向這些模型傳送最後一則助理訊息經過預填的請求，會回傳 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。

思考區塊不可修改

如果最近一則助理訊息中的 thinking 或 redacted_thinking 區塊，在傳回 API 之前遭到編輯、重新排序、過濾或重建，請求會回傳 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 4.7 及更新的模型已移除「extended thinking」（擴展思考）。向這些模型傳送 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.

請改用「adaptive thinking」（自適應思考）。遷移至自適應思考說明了參數對應方式，思考疑難排解則依症狀說明修正方法。

不支援自適應思考

僅支援擴展思考的模型（Claude 4.5 及更早的模型）會拒絕 thinking: {"type": "adaptive"}，並回傳 400 invalid_request_error：

adaptive thinking is not supported on this model

在這些模型上，請使用 thinking: {"type": "enabled", "budget_tokens": N}。設定方式請參閱擴展思考，依症狀的修正方法請參閱思考疑難排解。

無法停用思考

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5 與 Claude Mythos Preview 上，思考功能一律開啟。向這些模型傳送 thinking: {"type": "disabled"} 會回傳 400 invalid_request_error。除了 Claude Mythos Preview 以外，這些模型的錯誤訊息為：

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Claude Mythos Preview 是這些模型中唯一接受擴展思考的模型，其錯誤訊息為：

"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 Sonnet 5.5 上，思考無法設為 disabled。如需最低的思考設定，請使用 thinking: {"type": "between_tools"}，此設定會關閉事前思考。傳送 thinking: {"type": "disabled"} 會回傳 400 invalid_request_error，訊息如下：

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

在 xhigh 或 max effort 下，使用 between_tools 的請求也會回傳 400 invalid_request_error。由於 between_tools 沒有事前思考，訊息會指出思考已停用：

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

使用 between_tools 時，effort 無法在對話中途變更：如果個別訊息的 output_config.effort 與目前生效的等級不同，會回傳 400 錯誤。錯誤訊息會標示設定新等級的那則訊息的位置：

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

在這兩則訊息中，「enable thinking」指的是自適應思考：請省略 thinking 欄位，或傳送 thinking: {"type": "adaptive"}。Claude Sonnet 5.5 會以 400 錯誤拒絕 "enabled"。如需在每個回合使用不同的 effort，請使用自適應思考。

向 Claude Sonnet 5.5 以外的任何模型傳送 thinking: {"type": "between_tools"}，會回傳 400 invalid_request_error：

"thinking.type.between_tools" is not supported for this model.

修正方法請參閱思考疑難排解，其中涵蓋 between_tools 與 effort 相關錯誤。

省略 thinking 參數時，請求會以自適應思考執行。如果想讓回應中不包含思考內容，但又不關閉思考，請在思考設定中設定 display: "omitted"。請參閱思考疑難排解。

不支援強制工具使用

Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 Claude Mythos 5.1 不支援「forced tool use」（強制工具使用）。向這些模型傳送 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 會回傳 400 invalid_request_error，在 token 計數端點上也是如此：

tool_choice: type "tool" and "any" are not supported for this model.

這些模型接受 tool_choice: {"type": "auto"}（預設值）與 {"type": "none"}。如需確保工具輸入符合結構描述，請將 auto 搭配嚴格工具使用；如果需要回應本身採用固定的 JSON 結構，請使用結構化輸出。請參閱強制工具使用。

不支援的電腦使用工具版本

在 Claude API 與 Google Cloud 上，Claude Opus 5.5 與 Claude Sonnet 5.5 僅支援以 computer_toolset_20260801 工具集形式使用電腦使用。在這些平台上，如果向任一模型傳送舊版 computer_20251124 類型的 tools 項目（並附上該工具的 beta 標頭），會回傳 400 invalid_request_error。訊息會先指出被拒絕的類型，再於 Did you mean one of 之後列出該模型接受的工具類型。以 Claude Opus 5.5 為例，訊息開頭為：

'claude-opus-5-5' does not support tool types: computer_20251124.

對於所請求模型不支援的任何 Anthropic 定義工具類型，API 都會回傳相同的訊息。請在不使用 beta 標頭的情況下宣告 {"type": "computer_toolset_20260801"}，並依照從 computer_20251124 遷移中的說明更新您的代理迴圈。支援此工具集的較早模型會繼續接受 computer_20251124，Amazon Bedrock 上的 Claude Opus 5.5 和 Claude Sonnet 5.5 也是如此。

思考區塊與對話不再相符

在 Claude Fable 5.1、Claude Opus 5.5 和 Claude Sonnet 5.5 上，只有在重播的思考區塊之前的 system 提示、tools 與訊息都未變更時，API 才會接受該區塊。對於 2026 年 8 月 31 日當天或之後建立的新帳戶，以及任何將 thinking.block_binding.prefix_mismatch_behavior 設為 "error" 的請求，如果重播區塊之前的歷史記錄已變更，該區塊會被拒絕，並回傳 400 invalid_request_error（若設為 "drop_block"，API 會捨棄該區塊，請求仍會成功）。訊息開頭會標示第一個失敗區塊的位置：

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

如果沒有附上 thinking-binding-controls-2026-08-01 beta 標頭，訊息中也會提及該標頭。請讓對話歷史記錄保持僅附加，或附上 beta 標頭並設定 prefix_mismatch_behavior: "drop_block"，以捨棄該區塊並繼續。在 Claude Sonnet 5.5 上，block_binding 僅適用於 thinking: {"type": "adaptive"}。使用 between_tools 時，請讓歷史記錄保持僅附加，或從經過編輯的回合起移除所有思考區塊。如果區塊來自目標模型無法讀取的模型，該區塊會被捨棄，而不會遭到拒絕。請參閱保持前綴不變與思考疑難排解。

如果傳送 thinking.block_binding 時沒有附上 thinking-binding-controls-2026-08-01 beta 標頭，會回傳 400 invalid_request_error，其訊息結尾為：

block_binding: Extra inputs are not permitted

請加上該標頭，或移除該欄位。

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

後續步驟