Handle streaming refusals

Starting with Claude 4 models, streaming responses from Claude's API return stop_reason: "refusal" when streaming classifiers intervene to handle potential policy violations. This safety feature helps maintain content compliance during real-time streaming.

API response format

When streaming classifiers detect content that violates Anthropic's policies, the API returns this response:

{
  "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."
  }
}

In the event stream, stop_details arrives on the message_delta event alongside stop_reason.

Reset context after refusal

When you receive stop_reason: refusal, you must reset the conversation context before continuing. You can remove or rephrase the turn that triggered the refusal, or clear the conversation history entirely. Attempting to continue without resetting will result in continued refusals.

Implementation guide

Here's how to detect and handle streaming refusals in your application:

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",
    ) as stream:
        for event in stream:
            # Check for refusal in message delta
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")

Current refusal types

The API currently handles refusals in three different ways:

Best practices

• Monitor for refusals: Include stop_reason: refusal checks in your error handling
• Reset automatically: Implement automatic context reset when refusals are detected
• Fall back to another model: Configure server-side fallback or the SDK middleware so refused requests are retried on another Claude model instead of surfacing a refusal to the user
• Redeem fallback credit on manual retries: If you build the retry yourself, pass the refusal's fallback credit token so the retry doesn't pay the prompt-cache cost twice
• Provide custom messaging: Create user-friendly messages for better UX when refusals occur
• Track refusal patterns: Monitor refusal frequency to identify potential issues with your prompts

Migration notes

If you built refusal handling when this feature first shipped, or you're adding it to an existing integration, check the following:

• Refusals are responses, not errors. A refusal arrives as a successful HTTP 200 response with stop_reason: "refusal", so monitoring built only on error rates won't surface it. Track refusals as their own signal.
• Refusals include structured detail. On every model, a refusal also includes a stop_details object that identifies the policy category behind the decline. See Refusals and fallback for the full response shape.
• Retry on a different model. Re-sending a refused request to the same model usually results in another refusal. Instead of only resetting context, retry on a fallback model with server-side fallback, the SDK middleware, or a manual retry, and redeem fallback credit when you build the retry yourself.
• Check batch results for refusals. A refused request in a Message Batch is returned as a succeeded result with stop_reason: "refusal", not as an errored result.
• Centralize handling on stop_reason. The API continues to consolidate refusal handling around stop_reason: "refusal", so branch on the stop reason rather than on model-specific behavior.

Next steps