--- title: Claude API 錯誤 url: https://platform.claude.com/docs/zh-TW/api/errors description: 了解 Claude API 回傳的 HTTP 狀態碼、錯誤回應結構與請求 ID，並使用 SDK 的型別化例外處理錯誤。 --- ## HTTP 錯誤 API 遵循可預測的 HTTP 錯誤碼格式： * 400 - `invalid_request_error`：您的請求格式或內容有問題。此錯誤類型也可能用於本節未列出的其他 4XX 狀態碼。當用量達到您為組織或工作區[設定的支出限制](https://platform.claude.com/docs/zh-TW/api/rate-limits#setting-your-own-spend-limit)時，API 也會回傳 400；但 [Claude Code 工作區](https://platform.claude.com/docs/zh-TW/manage-claude/workspaces#claude-code-workspace)上的限制除外，該情況可能改為回傳 429。 * 401 - `authentication_error`：您的 [API 金鑰](https://platform.claude.com/docs/zh-TW/get-api-key)有問題（例如格式錯誤、已撤銷或已過期；請參閱[金鑰到期](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-expiration)）。在 Claude Platform on AWS 上，這也可能表示您的 AWS 憑證或 SigV4 簽章有問題。 * 402 - `billing_error`：您的帳單或付款資訊有問題。請在 [Claude Console](https://platform.claude.com) 中檢查您的付款詳細資料；若您使用的是 Claude Platform on AWS，請在 AWS Marketplace 中檢查。 * 403 - `permission_error`：您的 API 金鑰沒有使用指定資源的權限。請在 [Claude Console](https://platform.claude.com) 中檢查您組織的存取權限與工作區設定。 * 404 - `not_found_error`：找不到所請求的資源。請檢查端點路徑以及請求 URL 中的任何資源 ID。 * 409 - `conflict_error`：請求與資源的目前狀態衝突。例如，資源被同時修改，或某個必須唯一的值已被使用。請解決衝突後再重試請求。 * 413 - `request_too_large`：請求超過允許的最大位元組數。各端點的上限請參閱[請求大小限制](https://platform.claude.com/docs/zh-TW/api/errors#request-size-limits)。 * 429 - `rate_limit_error`：您的組織已達到[速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits)、已達到其用量層級的每月支出上限，或已達到 Claude Code 工作區的支出限制。層級支出上限造成的 429 沒有 `retry-after` 標頭，且在存取恢復前會持續失敗；如何辨識此情況，請參閱[達到支出上限](https://platform.claude.com/docs/zh-TW/api/rate-limits#reaching-your-spend-cap)。 * 500 - `api_error`：Anthropic 系統內部發生非預期的錯誤。請以「exponential backoff」（指數退避）重試請求；若錯誤持續發生，請附上[請求 ID](https://platform.claude.com/docs/zh-TW/api/errors#request-id) 聯絡支援團隊。 * 504 - `timeout_error`：請求在處理期間逾時。對於長時間執行的請求，請考慮使用[串流 Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)。更多選項請參閱[長時間請求](https://platform.claude.com/docs/zh-TW/api/errors#long-requests)。 * 529 - `overloaded_error`：API 暫時過載。 當所有使用者的整體流量偏高時，API 可能會發生 529 錯誤。 在少數情況下，如果您的組織用量急遽增加，您可能會因為 API 的加速限制而看到 429 錯誤。為避免觸及加速限制，請逐步提升流量並維持一致的使用模式。 官方 SDK 會以指數退避自動重試暫時性失敗（例如連線錯誤、速率限制和 5xx 伺服器錯誤），預設重試兩次，並在存在 `retry-after` 標頭時遵循該標頭。SDK 用戶端接受 `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) 來設定或停用此行為。 透過「server-sent events」（伺服器傳送事件），即 SSE，接收[串流](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)回應時，錯誤可能在 API 回傳 200 回應之後才發生。在這種情況下，錯誤處理不會遵循這些標準機制。串流中途錯誤的結構請參閱[錯誤事件](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming#error-events)。 ## 請求大小限制 API 會強制執行以下請求大小限制： | 端點類型 | 最大請求大小 | | -------------------------------------------------------------------------------------- | ------ | | Messages API | 32 MB | | Token Counting API | 32 MB | | [Batch API](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing) | 256 MB | | [Files API](https://platform.claude.com/docs/zh-TW/build-with-claude/files) | 500 MB | 如果超過這些限制，您會收到 413 `request_too_large` 錯誤。在直接使用的 Claude API 上，此錯誤由 Cloudflare 在請求抵達 API 伺服器之前回傳。 ## 錯誤結構 API 一律以 JSON 格式回傳錯誤，其中包含一個頂層 `error` 物件，且該物件一定會有 `type` 與 `message` 值。回應中也會包含 `request_id` 欄位，方便追蹤與除錯。例如： ```json JSON { "type": "error", "error": { "type": "not_found_error", "message": "The requested resource could not be found." }, "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" } ``` 依照[版本控制](https://platform.claude.com/docs/zh-TW/api/versioning)政策，這些物件中的值可能會擴充，`type` 值也可能隨時間增加。 ## SDK 錯誤類型 官方 SDK 會針對這些錯誤拋出型別化例外，而不是回傳原始 JSON。例如，404 會以 `anthropic.NotFoundError` (typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`) 的形式呈現。Go SDK 對所有狀態都使用同一個錯誤類型 `*anthropic.Error`：請依據 `StatusCode` 進行分支處理。請捕捉 SDK 的型別化類別，而不是以字串比對錯誤訊息，並優先處理最具體的類別。您所用 SDK 的頁面記載了完整的例外階層： * [Python](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/ruby#handling-errors) ## 請求 ID 每個 API 回應都包含一個唯一的 `request-id` 標頭，其值類似 `req_018EeWyXxfu5pfWkrYcMdjWG`。相同的識別碼也會以 `request_id` 欄位出現在[錯誤回應主體](https://platform.claude.com/docs/zh-TW/api/errors#error-shapes)中。就特定請求聯絡支援團隊時，請附上此 ID，以便快速解決您的問題。 在 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/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 則透過[中介軟體](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/middleware)提供。除了 Ruby 以外，所有 SDK 都可以使用 `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto`; php: `->raw`) 讀取其他[回應標頭](https://platform.claude.com/docs/zh-TW/api/overview#response-headers)，例如 `anthropic-organization-id` 與 [`anthropic-workspace-id`](https://platform.claude.com/docs/zh-TW/manage-claude/workspaces#identify-the-workspace-behind-an-api-response)。在 Ruby 中，請使用同一個中介軟體。在 Claude Platform on AWS 上，也請使用原始回應存取器讀取 AWS 請求 ID（`x-amzn-requestid`）： ```bash cURL # 印出回應標頭（包含 request-id）；捨棄回應主體 curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # 使用 --debug 時，request-id 標頭會輸出至 stderr： ant --debug messages create \ --model claude-sonnet-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const message = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }); console.log("Request ID:", message._request_id); ``` ```csharp C# AnthropicClient client = new(); using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }] }); Console.WriteLine($"Request ID: {response.RequestID}"); ``` ```go Go client := anthropic.NewClient() var response *http.Response _, err := client.Messages.New( context.Background(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithResponseInto(&response), ) if err != nil { panic(err) } fmt.Println("Request ID:", response.Header.Get("request-id")) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); HttpResponseFor response = client.messages().withRawResponse().create( MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .build() ); IO.println("Request ID: " + response.requestId().orElse(null)); } ``` ```php PHP $client = new Client(); $response = $client->messages->raw->create([ 'model' => 'claude-sonnet-5', 'maxTokens' => 1024, 'messages' => [['role' => 'user', 'content' => 'Hello, Claude']], ]); echo 'Request ID: ' . $response->getHeaderLine('request-id') . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new # 在每個請求的 middleware（中介軟體）中讀取回應標頭，它會接收 # SDK 解析前的原始 HTTP 回應 request_id = nil read_request_id = lambda do |request, call_next| response = call_next.call(request) # response.headers 中的鍵皆為小寫 request_id = response.headers["request-id"] response end client.messages.create( model: Anthropic::Model::CLAUDE_SONNET_5, max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }], request_options: { middleware: [read_request_id] } ) puts "Request ID: #{request_id}" ``` ```python Python (Claude Platform on AWS) from anthropic import AnthropicAWS client = AnthropicAWS(aws_region="us-west-2") response = client.messages.with_raw_response.create( model="claude-opus-5-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello, Claude"}], ) print(f"AWS request ID: {response.headers.get('x-amzn-requestid')}") message = response.parse() print(f"Anthropic request ID: {message._request_id}") ``` ```typescript TypeScript (Claude Platform on AWS) import AnthropicAws from "@anthropic-ai/aws-sdk"; const client = new AnthropicAws({ awsRegion: "us-west-2" }); const { response: raw, request_id } = await client.messages .create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }) .withResponse(); console.log("AWS request ID:", raw.headers.get("x-amzn-requestid")); console.log("Anthropic request ID:", request_id); ``` 其他語言的 Claude Platform on AWS 請求 ID 範例，請參閱[請求 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws#request-ids)。 ## 長時間請求 對於長時間執行的請求，尤其是超過 10 分鐘的請求，請考慮使用[串流 Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming) 或 [Message Batches API](https://platform.claude.com/docs/zh-TW/api/messages/batches/create)。 請避免在未使用[串流 Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming) 或 [Message Batches API](https://platform.claude.com/docs/zh-TW/api/messages/batches/create) 的情況下設定較大的 `max_tokens` 值： * 某些網路可能會在一段不固定的時間後中斷閒置連線，這 可能導致請求失敗或逾時，而未收到來自 Anthropic 的回應。 * 各網路的可靠性不同。[Message Batches API](https://platform.claude.com/docs/zh-TW/api/messages/batches/create) 可讓您 輪詢結果，而不需要不中斷的網路連線，藉此協助您管理網路問題的風險。 如果您正在建構直接的 API 整合，設定 [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html) 可以在某些網路上降低閒置連線逾時的影響。 [SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview) 會驗證您的非串流 Messages API 請求預期不會超過 10 分鐘的逾時限制。它們也會為 TCP keep-alive 設定 socket 選項。 如果您不需要逐步處理事件，SDK 可以替您讀取整個串流並回傳完整的 `Message` 物件，與非串流呼叫所回傳的內容完全相同： curl 請求會印出原始串流事件，無法將其組合成最終訊息。若要從串流取得完整的 `Message` 物件，請使用 [Claude SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview)。 ```bash CLI # CLI 會串流傳送事件；--format jsonl 每行輸出一個事件 ant messages create --stream --format jsonl <<'YAML' model: claude-sonnet-5 max_tokens: 128000 messages: - role: user content: Write a detailed analysis... YAML ``` ```python Python 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")) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }], model: "claude-sonnet-5" }); const message = await stream.finalMessage(); const textBlock = message.content.find((block) => block.type === "text"); if (textBlock && textBlock.type === "text") { console.log(textBlock.text); } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 128000, Messages = [new() { Role = Role.User, Content = "Write a detailed analysis..." }] }; var message = await client.Messages.CreateStreaming(parameters).Aggregate(); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 128000, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Write a detailed analysis...")), }, }) message := anthropic.Message{} for stream.Next() { event := stream.Current() if err := message.Accumulate(event); err != nil { log.Fatal(err) } } if err := stream.Err(); err != nil { log.Fatal(err) } for _, block := range message.Content { if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { fmt.Println(textBlock.Text) break } } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(128000L) .addUserMessage("Write a detailed analysis...") .build(); MessageAccumulator accumulator = MessageAccumulator.create(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(accumulator::accumulate); } Message message = accumulator.message(); message.content().stream() .filter(ContentBlock::isText) .findFirst() .flatMap(ContentBlock::text) .ifPresent(textBlock -> IO.println(textBlock.text())); } ``` ```php PHP use Anthropic\Lib\Streaming\MessageAccumulator; $client = new Client(); $stream = $client->messages->createStream( model: 'claude-sonnet-5', maxTokens: 128000, messages: [['role' => 'user', 'content' => 'Write a detailed analysis...']], ); $accumulator = MessageAccumulator::forMessages(); foreach ($stream as $event) { $accumulator->accumulate($event); } echo array_find($accumulator->message()->content, static fn ($block): bool => $block->type === 'text')->text; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.stream( model: "claude-sonnet-5", max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }] ).accumulated_message puts message.content.find { it.type == :text }.text ``` 更多詳細資訊請參閱[串流訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming#get-the-final-message-without-handling-events)。 ## 常見驗證錯誤 ### 不支援預填 Claude 4.6 及更新的模型以及 [Claude Mythos Preview](https://anthropic.com/glasswing) 不支援「prefill」（預填）助理訊息。向這些模型中的任何一個傳送最後一則助理訊息為預填內容的請求，會回傳 400 `invalid_request_error`： ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "This model does not support assistant message prefill. The conversation must end with a user message." } } ``` 請改為在支援的模型上使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)、系統提示指示，或 [`output_config.format`](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#usage)。 ### 思考區塊不可修改 如果最近一則助理訊息中的 `thinking` 或 `redacted_thinking` 區塊，在傳回 API 之前遭到編輯、重新排序、過濾或重建，請求會回傳 400 `invalid_request_error`。錯誤訊息開頭會標示出問題區塊的位置（例如 `messages.1.content.0`），並包含： ```text wrap `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`。請參閱[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified)、[保留思考區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserving-thinking-blocks)與[保留的思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserved-thinking)。 ### 不支援擴展思考 Claude 4.7 及更新的模型已移除「extended thinking」（擴展思考）。向這些模型傳送 `thinking: {"type": "enabled"}` 會回傳 400 `invalid_request_error`： ```text wrap "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` 請改用「[adaptive thinking](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)」（自適應思考）。[遷移至自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#migrating-to-adaptive-thinking)說明了參數對應方式，[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled)則依症狀說明修正方法。 ### 不支援自適應思考 僅支援擴展思考的模型（Claude 4.5 及更早的模型）會拒絕 `thinking: {"type": "adaptive"}`，並回傳 400 `invalid_request_error`： ```text wrap adaptive thinking is not supported on this model ``` 在這些模型上，請使用 `thinking: {"type": "enabled", "budget_tokens": N}`。設定方式請參閱[擴展思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking)，依症狀的修正方法請參閱[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive)。 ### 無法停用思考 在 Claude Fable 5.1、[Claude Mythos 5.1](https://platform.claude.com/docs/zh-TW/models/mythos-5-1/overview)、Claude Fable 5、[Claude Mythos 5](https://platform.claude.com/docs/zh-TW/models/mythos-5/overview)、Claude Opus 5.5 和 [Claude Mythos Preview](https://anthropic.com/glasswing) 上，思考功能始終開啟。向這些模型中的任何一個傳送 `thinking: {"type": "disabled"}` 會回傳 400 `invalid_request_error`。在除 Claude Mythos Preview 以外的所有這些模型上，訊息內容為： ```text wrap "thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` 在 Claude Mythos Preview（這些模型中唯一接受擴展思考的模型）上，訊息內容為： ```text wrap "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`，訊息如下： ```text wrap 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](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 下，使用 `between_tools` 的請求也會回傳 400 `invalid_request_error`。訊息指出思考已停用，因為 `between_tools` 沒有預先思考： ```text wrap 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 錯誤。錯誤會指出設定新等級之訊息的位置： ```text wrap 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`： ```text wrap "thinking.type.between_tools" is not supported for this model. ``` 修正方法請參閱[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools)，其中涵蓋 `between_tools` 和 effort 相關錯誤。 省略 `thinking` 參數時，請求會以自適應思考執行。若要在不關閉思考的情況下讓回應中不包含思考內容，請在思考設定中設定 `display: "omitted"`。請參閱[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled)。 ### 不支援強制工具使用 Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 [Claude Mythos 5.1](https://platform.claude.com/docs/zh-TW/models/mythos-5-1/overview) 不支援「forced tool use」（強制工具使用）。向這些模型中的任何一個傳送 `tool_choice: {"type": "any"}` 或 `tool_choice: {"type": "tool", "name": "..."}`（包括在 [token 計數端點](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)上），會回傳 400 `invalid_request_error`： ```text wrap tool_choice: type "tool" and "any" are not supported for this model. ``` `tool_choice: {"type": "auto"}`（預設值）和 `{"type": "none"}` 可被接受。請搭配[嚴格工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/strict-tool-use)使用 `auto`，以確保工具輸入符合結構描述；若您需要回應本身採用固定的 JSON 結構，請使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)。請參閱[強制工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/define-tools#forcing-tool-use)。 ### 不支援的電腦使用工具版本 在 Claude API 和 Google Cloud 上，Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 僅以 `computer_toolset_20260801` 工具集的形式支援[電腦使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool)。在這些平台上，向這些模型中的任何一個傳送較早的 `computer_20251124` 或 `computer_20250124` 類型的 `tools` 項目（並附上該工具的 beta 標頭），會回傳 400 `invalid_request_error`。訊息會指出被拒絕的類型，然後在 `Did you mean one of` 之後列出該模型接受的工具類型。對於 Claude Opus 5.5，訊息開頭為： ```text wrap 'claude-opus-5-5' does not support tool types: computer_20251124. ``` 對於所請求模型不支援的任何 Anthropic 定義工具類型，API 都會回傳相同的訊息。請在不附 beta 標頭的情況下宣告 `{"type": "computer_toolset_20260801"}`，並依照[從 `computer_20251124` 遷移](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)中的說明更新您的代理迴圈。若要從 `computer_20250124` 遷移，請參閱 Claude Haiku 5.5 遷移指南中的[將電腦使用遷移至工具集](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#computer-use-toolset)。支援該工具集的較早模型仍接受 `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 會捨棄該區塊，請求則會成功）。訊息以第一個失敗區塊的位置開頭： ```text wrap 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"}` 時，請讓歷史記錄保持僅附加，或從被編輯的回合起移除思考區塊。來自目標模型無法讀取之模型的區塊會被捨棄，而不是被拒絕。請參閱[保持前綴不變](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#prefix-check)和[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-block-signature)。 在未使用 `thinking-binding-controls-2026-08-01` [beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers)的情況下傳送 `thinking.block_binding`，會回傳 400 `invalid_request_error`，其訊息結尾為： ```text wrap block_binding: Extra inputs are not permitted ``` 請加入該標頭，或移除該欄位。 ### 已停用對外 Web 身分聯合（Claude Platform on AWS） 如果對 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) 的每個請求都回傳 `"Outbound web identity federation is disabled for your account"`，請在每個 AWS 帳戶中執行一次 `aws iam enable-outbound-web-identity-federation`。詳細資訊請參閱[啟用對外 Web 身分聯合](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation)。 ## 後續步驟 依症狀修正思考設定的 400 錯誤、空白思考區塊，以及因 `max_tokens` 而停止的問題。 為了防止濫用並管理 API 容量，組織使用 Claude API 的用量設有限制。 使用伺服器傳送事件逐步串流 Messages API 回應，包括文字、工具使用與擴展思考的增量內容。