串流拒絕 - Claude Platform Docs

從 Claude 4 模型開始，當串流分類器介入處理潛在的政策違規時，Claude API 的串流回應會回傳 stop_reason: "refusal"。此安全功能有助於在即時串流期間維持內容合規性。

本頁面說明拒絕如何出現在串流回應中。如需了解每個 stop_reason 值及其處理方式，請參閱停止原因與備援。若要在另一個 Claude 模型上重試被拒絕的請求，請參閱拒絕與備援。

API 回應格式

當串流分類器偵測到違反 Anthropic 政策的內容時，API 會回傳以下回應：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal"
}

回應中不會包含額外的拒絕訊息。您必須自行處理回應並提供適當的使用者介面訊息。

拒絕後重設上下文

當您收到 stop_reason: refusal 時，必須先重設對話上下文才能繼續。您可以移除或改寫觸發拒絕的那一輪對話，或完全清除對話歷史記錄。若未重設就嘗試繼續，將會持續收到拒絕。

即使回應被拒絕，回應中仍會提供用量指標。

當拒絕在 Claude 產生任何輸出之前就發生時，您在 Claude API 上不會被收取該請求的費用，且該回應中的用量計數僅供參考。當 Claude 在拒絕之前已產生輸出時，您將被收取該請求的費用。

重設上下文並非唯一的復原方式。您也可以在不同的 Claude 模型上重試被拒絕的請求，拒絕與備援頁面說明了如何透過伺服器端備援、SDK 中介軟體或手動重試來進行設定。

實作指南

以下說明如何在您的應用程式中偵測並處理串流拒絕：

目前的拒絕類型

API 目前以三種不同方式處理拒絕：

拒絕類型	回應格式	發生時機
串流分類器拒絕	`stop_reason`: `refusal`	串流期間內容違反政策時
API 輸入與著作權驗證	400 錯誤碼	輸入未通過驗證檢查時
模型產生的拒絕	標準文字回應	模型本身決定拒絕時

未來的 API 版本將擴展 stop_reason: refusal 模式，以統一所有類型的拒絕處理方式。

最佳實務

監控拒絕： 在您的錯誤處理中納入 stop_reason: refusal 檢查
自動重設： 在偵測到拒絕時實作自動上下文重設
備援至另一個模型： 設定伺服器端備援或 SDK 中介軟體，讓被拒絕的請求在另一個 Claude 模型上重試，而非直接向使用者顯示拒絕
在手動重試時兌換備援額度： 如果您自行建置重試機制，請傳遞該拒絕的備援額度權杖，以免重試時重複支付提示快取成本
提供自訂訊息： 建立使用者友善的訊息，以在發生拒絕時提供更好的使用者體驗
追蹤拒絕模式： 監控拒絕頻率，以找出提示中的潛在問題

遷移注意事項

如果您在此功能首次推出時就建置了拒絕處理機制，或正在將其加入現有的整合中，請檢查以下事項：

拒絕是回應，而非錯誤。 拒絕會以成功的 HTTP 200 回應形式送達，並帶有 stop_reason: "refusal"，因此僅基於錯誤率建立的監控機制無法偵測到它。請將拒絕作為獨立的訊號進行追蹤。
較新的模型會回傳更多詳細資訊。 在 Claude Fable 5 上，拒絕還會包含一個 stop_details 物件，用於識別拒絕背後的政策類別。完整的回應結構請參閱拒絕與備援。
在不同的模型上重試。 將被拒絕的請求重新傳送至同一個模型通常會再次收到拒絕。與其僅重設上下文，不如透過伺服器端備援、SDK 中介軟體或手動重試在備援模型上重試，並在自行建置重試機制時兌換備援額度。
檢查批次結果中的拒絕。 在訊息批次中被拒絕的請求會以帶有 stop_reason: "refusal" 的成功結果回傳，而非錯誤結果。
以 stop_reason 為中心進行處理。 API 持續將拒絕處理整合至 stop_reason: "refusal"，因此請根據停止原因進行分支處理，而非依據特定模型的行為。

後續步驟

拒絕與備援

在另一個 Claude 模型上重試被拒絕的請求，無論是伺服器端或在您的用戶端中。

停止原因與備援

每個 stop_reason 值及其處理方式。

串流訊息

串流回應並在 message_delta 事件送達時讀取 stop_reason。

client = anthropic.Anthropic()
messages = []


def reset_conversation():
    """Reset conversation context after refusal"""
    global messages
    messages = []
    print("Conversation reset due to refusal")


try:
    with client.messages.stream(
        max_tokens=1024,
        messages=messages + [{"role": "user", "content": "Hello"}],
        model="claude-opus-4-8",
    ) as stream:
        for event in stream:
            # 檢查訊息差異中是否有拒絕回應
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")

API 回應格式

拒絕後重設上下文

實作指南

目前的拒絕類型

最佳實務

遷移注意事項

後續步驟

API 回應格式

拒絕後重設上下文

實作指南

目前的拒絕類型

最佳實務

遷移注意事項

後續步驟