錯誤



HTTP 錯誤

API 遵循可預測的 HTTP 錯誤代碼格式：

• 400 - invalid_request_error：您的請求格式或內容有問題。此錯誤類型也可能用於本節未列出的其他 4XX 狀態碼。

• 401 - authentication_error：您的 API 金鑰有問題。在 AWS 上的 Claude Platform 中，這也可能表示您的 AWS 憑證或 SigV4 簽章有問題。

• 402 - billing_error：您的帳單或付款資訊有問題。請在 Claude Console 中檢查您的付款詳細資訊，如果您使用的是 AWS 上的 Claude Platform，則請在 AWS Marketplace 中檢查。

• 403 - permission_error：您的 API 金鑰沒有使用指定資源的權限。

• 404 - not_found_error：找不到請求的資源。

• 413 - request_too_large：請求超過允許的最大位元組數。請參閱請求大小限制以了解各端點的上限。

• 429 - rate_limit_error：您的帳戶已達到速率限制。

• 500 - api_error：Anthropic 系統內部發生了意外錯誤。

• 504 - timeout_error：請求在處理過程中逾時。對於長時間執行的請求，請考慮使用串流。

• 529 - overloaded_error：API 暫時過載。

  

  當 API 在所有使用者中遇到高流量時，可能會發生 529 錯誤。

  在極少數情況下，如果您的組織使用量急劇增加，您可能會因為 API 的加速限制而看到 429 錯誤。為避免觸發加速限制，請逐步增加您的流量並維持一致的使用模式。

當透過 SSE 接收串流回應時，可能會在回傳 200 回應後發生錯誤，在這種情況下，錯誤處理將不會遵循這些標準機制。



請求大小限制

API 會強制執行請求大小限制以確保最佳效能：

如果您超過這些限制，將會收到 413 request_too_large 錯誤。在直接的 Claude API 上，此錯誤會在請求到達 API 伺服器之前由 Cloudflare 回傳。



錯誤格式

錯誤一律以 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 的值。當就特定請求聯絡支援團隊時，請附上此 ID 以協助快速解決您的問題。

在 AWS 上的 Claude Platform 中，回應包含兩個請求 ID：AWS 請求 ID（x-amzn-requestid，主要，在 CloudTrail 中建立索引）和 Anthropic 請求 ID（request-id，次要）。使用 AWS 請求 ID 進行 CloudTrail 查詢，使用 Anthropic 請求 ID 提交 Anthropic 支援工單。

官方 SDK 會在頂層回應物件上提供 Anthropic 請求 ID 作為屬性，其中包含 request-id 標頭的值。在 AWS 上的 Claude Platform 中，請使用原始回應存取器，以便同時從 HTTP 標頭讀取 AWS 請求 ID：

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

如需其他語言中 AWS 上的 Claude Platform 請求 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 選項。

如果您不需要逐步處理事件，請使用 .stream() 搭配 .get_final_message()（Python）或 .finalMessage()（TypeScript）來取得完整的 Message 物件，而無需撰寫事件處理程式碼：

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-8",
) as stream:
    message = stream.get_final_message()
print(message.content)

請參閱串流訊息以了解更多詳細資訊。



常見驗證錯誤



不支援預填

Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 不支援預填助理訊息。向這些模型中的任何一個傳送包含預填最後助理訊息的請求，將會回傳 400 invalid_request_error：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

請改用支援此功能的模型上的結構化輸出、系統提示指令，或 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 上的思考輸出。



已停用對外 Web 身分聯合（AWS 上的 Claude Platform）

如果對 AWS 上的 Claude Platform 的每個請求都回傳 "Outbound web identity federation is disabled for your account"，請針對每個 AWS 帳戶執行一次 aws iam enable-outbound-web-identity-federation。請參閱啟用對外 Web 身分聯合以了解詳細資訊。