Claude Platform Docs
API 參考使用 API

Claude API 錯誤

了解 Claude API 回傳的 HTTP 狀態碼、錯誤回應結構與請求 ID，並使用 SDK 的型別化例外來處理錯誤。

HTTP 錯誤

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

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

  • 401 - authentication_error：您的「API key」（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：您的組織已觸及「rate limit」（速率限制）、已達到其用量層級的每月支出上限，或已達到 Claude Code 工作區的支出限制。因層級支出上限而產生的 429 不含 retry-after 標頭，並會持續失敗，直到存取權恢復為止。如何辨識此情況，請參閱達到支出上限。

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

  • 504 - timeout_error：請求在處理期間逾時。對於長時間執行的請求，請考慮使用「streaming」（串流）Messages API。更多選項請參閱長時間請求。

  • 529 - overloaded_error：API 暫時過載。

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

透過「server-sent events」（伺服器傳送事件），即 SSE，接收串流回應時，錯誤可能在 API 回傳 200 回應之後才發生。在這種情況下，錯誤處理不會遵循上述標準機制。串流中途錯誤的結構請參閱錯誤事件。

請求大小限制

API 會強制執行以下請求大小限制：

端點類型最大請求大小
Messages API32 MB
Token Counting API32 MB
Batch API256 MB
Files API500 MB

如果超過這些限制，您會收到 413 request_too_large 錯誤。在直接使用 Claude API 時，Cloudflare 會在請求抵達 API 伺服器之前就回傳此錯誤。

錯誤結構

API 一律以 JSON 格式回傳錯誤。回應包含一個頂層 error 物件，其中一定會有 type 和 message 值。回應也包含 request_id 欄位，方便追蹤與除錯。例如：

JSON
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

依據版本控制政策，這些物件中的值可能會擴充，type 的值也可能隨時間增加。

SDK 錯誤類型

官方 SDK 不會回傳原始 JSON，而是針對這些錯誤拋出「typed exceptions」（型別化例外）。類別名稱與命名空間因語言而異。例如，404 在各語言中的呈現方式如下：

  • Python：anthropic.NotFoundError
  • Ruby：Anthropic::Errors::NotFoundError
  • Java：com.anthropic.errors.NotFoundException
  • Go：單一的 *anthropic.Error 值（依 StatusCode 分支處理）

請捕捉 SDK 的型別化類別，而不要以字串比對錯誤訊息，並優先處理最具體的類別。各 SDK 頁面都記載了完整的例外階層：

請求 ID

每個 API 回應都包含一個唯一的 request-id 標頭，其值類似 req_018EeWyXxfu5pfWkrYcMdjWG。相同的識別碼也會以 request_id 欄位出現在錯誤回應主體中。就特定請求聯絡支援團隊時，請附上此 ID，以便快速解決您的問題。

在 Claude Platform on AWS 上，回應包含兩個請求 ID：

  • AWS 請求 ID（x-amzn-requestid）：主要 ID，已在 CloudTrail 中建立索引。請用於 CloudTrail 查詢。
  • Anthropic 請求 ID（request-id）：次要 ID。請用於 Anthropic 支援工單。

各 SDK 取得請求 ID 的方式如下：

  • Python 和 TypeScript SDK：透過頂層回應物件上的 _request_id 屬性。
  • C#、Go、Java 和 PHP SDK：透過各自的原始回應存取器。
  • Ruby SDK：透過中介軟體。

這些機制，以及 Python 中的 with_raw_response 和 TypeScript 中的 .withResponse()，也能讀取任何其他回應標頭，例如 anthropic-organization-id 和 anthropic-workspace-id。在 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."
  }
}

請改用以下任一方式：

思考區塊不可修改

如果最近一則助理訊息中的 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.

使用「tool use」（工具使用）時，助理回合中的每個 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.

省略 thinking 參數，請求便會以自適應思考執行。若要在不關閉思考的情況下讓回應中不包含思考內容，請在思考設定中設定 display: "omitted"。請參閱思考功能疑難排解。

不支援強制工具使用

Claude Opus 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 僅支援以 computer_toolset_20260801 工具集形式使用電腦使用。在這些平台上，若傳送較早的 computer_20251124 類型 tools 項目（並附上該工具的 beta 標頭），會回傳 400 invalid_request_error。錯誤訊息會先指出遭拒絕的類型，再於 Did you mean one of 之後列出模型可接受的工具類型；訊息開頭如下：

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

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

思考區塊不再與對話相符

在 Claude Fable 5.1 和 Claude Opus 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"，以捨棄該區塊並繼續。來自目標模型無法讀取之模型的區塊會被捨棄，而不是遭到拒絕。請參閱保持前綴不變以及思考功能疑難排解。

在未使用 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 身分聯合。

後續步驟

思考功能疑難排解

依症狀排查思考設定的 400 錯誤、空白思考區塊，以及因 max_tokens 而停止的問題。

速率限制

為了防止濫用並管理 API 容量，Claude API 對組織的用量設有限制。

串流訊息

使用伺服器傳送事件逐步串流 Messages API 回應，包括文字、工具使用和擴展思考的增量內容。

Was this page helpful?