流式传输拒绝

从 Claude 4 模型开始，当流式传输分类器介入处理潜在的策略违规时，Claude API 的流式传输响应会返回 stop_reason: "refusal"。此安全功能有助于在实时流式传输期间维护内容合规性。



API 响应格式

当流式传输分类器检测到违反 Anthropic 策略的内容时，API 会返回以下响应：

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



拒绝后重置上下文

当您收到 stop_reason: refusal 时，必须在继续之前重置对话上下文。您可以删除或重新表述触发拒绝的那一轮对话，或者完全清除对话历史记录。如果不重置就尝试继续，将会导致持续的拒绝。



实现指南

以下是如何在您的应用程序中检测和处理流式传输拒绝：



当前的拒绝类型

API 目前以三种不同的方式处理拒绝：



最佳实践

• 监控拒绝： 在您的错误处理中包含 stop_reason: refusal 检查
• 自动重置： 在检测到拒绝时实现自动上下文重置
• 回退到另一个模型： 配置服务器端备用方案或 SDK 中间件，以便在另一个 Claude 模型上重试被拒绝的请求，而不是向用户显示拒绝
• 在手动重试时兑换备用额度： 如果您自行构建重试逻辑，请传递拒绝响应中的 fallback credit（备用额度）令牌，以避免重试时重复支付提示缓存成本
• 提供自定义消息： 创建用户友好的消息，以便在发生拒绝时提供更好的用户体验
• 跟踪拒绝模式： 监控拒绝频率，以识别您的提示中可能存在的问题



迁移说明

如果您在此功能首次发布时构建了拒绝处理逻辑，或者正在将其添加到现有集成中，请检查以下内容：

• 拒绝是响应，而非错误。 拒绝以带有 stop_reason: "refusal" 的成功 HTTP 200 响应形式到达，因此仅基于错误率构建的监控不会捕获到它。请将拒绝作为独立的信号进行跟踪。
• 较新的模型返回更多详细信息。 在 Claude Fable 5 上，拒绝还包含一个 stop_details 对象，用于标识拒绝背后的策略类别。有关完整的响应结构，请参阅拒绝与备用方案。
• 在不同的模型上重试。 将被拒绝的请求重新发送到同一模型通常会导致再次拒绝。不要仅重置上下文，而应通过服务器端备用方案、SDK 中间件或手动重试在备用模型上重试，并在自行构建重试逻辑时兑换备用额度。
• 检查批处理结果中的拒绝。 消息批处理中被拒绝的请求会作为带有 stop_reason: "refusal" 的成功结果返回，而不是作为错误结果返回。
• 围绕 stop_reason 集中处理。 API 会持续将拒绝处理整合到 stop_reason: "refusal" 上，因此请基于停止原因进行分支处理，而不是基于特定模型的行为。



后续步骤