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 用戶端接受 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，訊息如下：

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

在 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.

Claude Haiku 5.5 接受 thinking: {"type": "disabled"}，並對其套用與 between_tools 相同的兩項 effort 限制：在 xhigh 或 max effort 下，或個別訊息的 output_config.effort 與目前生效的等級不同時，請求會回傳 400 invalid_request_error，並附上前面所示的對應訊息。

在這兩則訊息中，「enable thinking」指的是自適應思考：省略 thinking 欄位或傳送 thinking: {"type": "adaptive"}。Claude Sonnet 5.5 和 Claude Haiku 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": "..."}（包括在 token 計數端點上），會回傳 400 invalid_request_error：

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 和 Claude Haiku 5.5 僅以 computer_toolset_20260801 工具集的形式支援電腦使用。在這些平台上，向這些模型中的任何一個傳送較早的 computer_20251124 或 computer_20250124 類型的 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_20250124 遷移，請參閱 Claude Haiku 5.5 遷移指南中的將電腦使用遷移至工具集。支援該工具集的較早模型仍接受 computer_20251124，Amazon Bedrock 上的 Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 也是如此。

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

在 Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 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 和 Claude Haiku 5.5 上，block_binding 僅適用於 thinking: {"type": "adaptive"}。在 Claude Sonnet 5.5 上使用 between_tools，或在 Claude Haiku 5.5 上使用 thinking: {"type": "disabled"} 時，請讓歷史記錄保持僅附加，或從被編輯的回合起移除思考區塊。來自目標模型無法讀取之模型的區塊會被捨棄，而不是被拒絕。請參閱保持前綴不變和思考疑難排解。

在未使用 thinking-binding-controls-2026-08-01 beta 標頭的情況下傳送 thinking.block_binding，會回傳 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 身分聯合。

後續步驟