處理串流拒絕

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

API 回應格式

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  }
}

在事件串流中，stop_details 會與 stop_reason 一同出現在 message_delta 事件中。

拒絕後重設上下文

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

實作指南

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

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-5-5",
    ) as stream:
        for event in stream:
            # 檢查 message delta 中是否有拒絕回應
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")

目前的拒絕類型

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

最佳實務

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

遷移注意事項

若您在此功能首次推出時便已建構拒絕處理機制，或正要將其加入既有的整合中，請檢查以下事項：

• 拒絕是回應，而非錯誤。 拒絕會以成功的 HTTP 200 回應形式送達，並帶有 stop_reason: "refusal"，因此僅依據錯誤率建立的監控無法發現它。請將拒絕作為獨立的訊號進行追蹤。
• 拒絕包含結構化細節。 在每個模型上，拒絕也會包含一個 stop_details 物件，用以識別拒絕背後的政策類別。請參閱拒絕與備援以了解完整的回應結構。
• 在不同模型上重試。 將被拒絕的請求重新傳送至同一模型通常會導致再次拒絕。與其僅重設上下文，不如透過伺服器端備援、SDK 中介軟體或手動重試在備援模型上重試，並在您自行建構重試機制時兌換備援額度。
• 檢查批次結果中的拒絕。 Message Batch 中被拒絕的請求會以成功結果的形式回傳，並帶有 stop_reason: "refusal"，而非以錯誤結果回傳。
• 以 stop_reason 集中處理。 API 持續將拒絕處理整合至 stop_reason: "refusal"，因此請依據停止原因進行分支判斷，而非依據特定模型的行為。

後續步驟