SPB Git

Repository Public

handle-streaming-refusals.md 13.4 KB 354 lines markdown

1---2title: Handle streaming refusals3url: https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals4description: Detect and handle refusal stop reasons in streaming responses, and retry refused requests on a fallback model.5---67Starting 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.89<Tip>10  This page covers how refusals appear in streaming responses. For every `stop_reason` value and how to handle it, see [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons). To retry refused requests on another Claude model, see [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).11</Tip>1213## API response format1415When streaming classifiers detect content that violates Anthropic's policies, the API returns this response:1617```json18{19  "role": "assistant",20  "content": [21    {22      "type": "text",23      "text": "Hello.."24    }25  ],26  "stop_reason": "refusal",27  "stop_details": {28    "type": "refusal",29    "category": "cyber",30    "explanation": "This request was declined because it could enable cyber harm."31  }32}33```3435In the event stream, `stop_details` arrives on the `message_delta` event alongside `stop_reason`.3637<Note>38  A `refusal` response from streaming classifiers includes a `stop_details` object with a `category` and a human-readable `explanation` that you can surface to the user. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the full response shape and the available categories.3940  On a refusal the `stop_details` object is always present, but its `category` and `explanation` fields can be `null`, for example when the refusal maps to no named category. Branch on `stop_reason` or `stop_details.type` rather than assuming `category` and `explanation` are populated, and provide your own user-facing messaging when they are `null`.41</Note>4243## Reset context after refusal4445When 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.4647<Note>48  Usage metrics are still provided in the response, even when the response is refused.4950  When a refusal arrives before Claude generates any output, you are not billed for the request on the Claude API, and the usage counts in that response are informational only. When Claude generates output before the refusal, you are billed for that request.51</Note>5253<Tip>54  Resetting context is not the only way to recover. You can also retry the refused request on a different Claude model, and the [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) page shows how to set that up with server-side fallback, the SDK middleware, or a manual retry.55</Tip>5657## Implementation guide5859Here's how to detect and handle streaming refusals in your application:6061<CodeGroup>62  ```bash cURL63  # Stream request and check for refusal64  response=$(curl -N https://api.anthropic.com/v1/messages \65    -H "anthropic-version: 2023-06-01" \66    -H "content-type: application/json" \67    -H "x-api-key: $ANTHROPIC_API_KEY" \68    -d '{69      "model": "claude-opus-5",70      "messages": [{"role": "user", "content": "Hello"}],71      "max_tokens": 1024,72      "stream": true73    }')7475  # Check for refusal in the stream76  if echo "$response" | grep -q '"stop_reason":"refusal"'; then77    echo "Response refused - resetting conversation context"78    # Reset your conversation state here79  fi80  ```8182  ```python Python83  client = anthropic.Anthropic()84  messages = []858687  def reset_conversation():88      """Reset conversation context after refusal"""89      global messages90      messages = []91      print("Conversation reset due to refusal")929394  try:95      with client.messages.stream(96          max_tokens=1024,97          messages=messages + [{"role": "user", "content": "Hello"}],98          model="claude-opus-5",99      ) as stream:100          for event in stream:101              # Check for refusal in message delta102              if event.type == "message_delta":103                  if event.delta.stop_reason == "refusal":104                      reset_conversation()105                      break106  except Exception as e:107      print(f"Error: {e}")108  ```109110  ```typescript TypeScript111  const client = new Anthropic();112  let messages: Anthropic.MessageParam[] = [];113114  function resetConversation() {115    // Reset conversation context after refusal116    messages = [];117    console.log("Conversation reset due to refusal");118  }119120  try {121    const stream = await client.messages.stream({122      messages: [...messages, { role: "user", content: "Hello" }],123      model: "claude-opus-5",124      max_tokens: 1024125    });126127    for await (const event of stream) {128      // Check for refusal in message delta129      if (event.type === "message_delta" && event.delta.stop_reason === "refusal") {130        resetConversation();131        break;132      }133    }134  } catch (error) {135    console.error("Error:", error);136  }137  ```138139  ```csharp C#140  List<Message> messages = new();141  AnthropicClient client = new();142143  var parameters = new MessageCreateParams144  {145      Model = Model.ClaudeOpus5,146      MaxTokens = 1024,147      Messages = [new() { Role = Role.User, Content = "Hello" }]148  };149150  try151  {152      await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))153      {154          if (155              streamEvent.TryPickDelta(out var deltaEvent)156              && deltaEvent.Delta.StopReason == StopReason.Refusal157          )158          {159              ResetConversation();160              break;161          }162      }163  }164  catch (Exception e)165  {166      Console.WriteLine($"Error: {e.Message}");167  }168169  void ResetConversation()170  {171      messages.Clear();172      Console.WriteLine("Conversation reset due to refusal");173  }174  ```175176  ```go Go177  var messages []anthropic.MessageParam178179  func resetConversation() {180  	messages = []anthropic.MessageParam{}181  	fmt.Println("Conversation reset due to refusal")182  }183  // ...184  	client := anthropic.NewClient()185186  	stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{187  		Model:     anthropic.ModelClaudeOpus5,188  		MaxTokens: 1024,189  		Messages: []anthropic.MessageParam{190  			anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),191  		},192  	})193194  streamLoop:195  	for stream.Next() {196  		event := stream.Current()197  		switch eventVariant := event.AsAny().(type) {198  		case anthropic.MessageDeltaEvent:199  			if eventVariant.Delta.StopReason == anthropic.StopReasonRefusal {200  				resetConversation()201  				break streamLoop202  			}203  		}204  	}205206  	if err := stream.Err(); err != nil {207  		log.Fatal(err)208  	}209  ```210211  ```java Java212  import com.anthropic.core.http.StreamResponse;213  import com.anthropic.models.messages.RawMessageStreamEvent;214  import com.anthropic.models.messages.StopReason;215  // ...216217  List<MessageParam> messages = new ArrayList<>();218219  void main() {220      AnthropicClient client = AnthropicOkHttpClient.fromEnv();221222      MessageCreateParams params = MessageCreateParams.builder()223          .model(Model.CLAUDE_OPUS_5)224          .maxTokens(1024L)225          .addUserMessage("Hello")226          .build();227228      try (StreamResponse<RawMessageStreamEvent> stream = client.messages().createStreaming(params)) {229          stream.stream().forEach(event -> {230              event.messageDelta().ifPresent(deltaEvent -> {231                  deltaEvent.delta().stopReason().ifPresent(stopReason -> {232                      if (stopReason.equals(StopReason.REFUSAL)) {233                          resetConversation();234                      }235                  });236              });237          });238      } catch (Exception e) {239          System.err.println("Error: " + e.getMessage());240      }241  }242243  void resetConversation() {244      messages.clear();245      IO.println("Conversation reset due to refusal");246  }247  ```248249  ```php PHP250  $client = new Client();251  $messages = [];252253  function resetConversation(&$messages) {254      $messages = [];255      echo "Conversation reset due to refusal\n";256  }257258  try {259      $stream = $client->messages->createStream(260          maxTokens: 1024,261          messages: [262              ['role' => 'user', 'content' => 'Hello']263          ],264          model: 'claude-opus-5',265      );266267      foreach ($stream as $event) {268          if ($event->type === 'message_delta' && $event->delta->stopReason === 'refusal') {269              resetConversation($messages);270              break;271          }272      }273  } catch (Exception $e) {274      echo "Error: " . $e->getMessage() . "\n";275  }276  ```277278  ```ruby Ruby279  client = Anthropic::Client.new280  messages = []281282  def reset_conversation(messages)283    messages.clear284    puts "Conversation reset due to refusal"285  end286287  begin288    stream = client.messages.stream(289      model: :"claude-opus-5",290      max_tokens: 1024,291      messages: [{ role: "user", content: "Hello" }]292    )293294    stream.each do |event|295      if event.type == :message_delta && event.delta.stop_reason == :refusal296        reset_conversation(messages)297        break298      end299    end300  rescue => e301    puts "Error: #{e.message}"302  end303  ```304</CodeGroup>305306## Current refusal types307308The API currently handles refusals in three different ways:309310| Refusal type                       | Response format              | When it occurs                                  |311| ---------------------------------- | ---------------------------- | ----------------------------------------------- |312| Streaming classifier refusals      | **`stop_reason`: `refusal`** | During streaming when content violates policies |313| API input and copyright validation | 400 error codes              | When input fails validation checks              |314| Model-generated refusals           | Standard text responses      | When the model itself refuses                   |315316## Best practices317318* **Monitor for refusals:** Include **`stop_reason`: `refusal`** checks in your error handling319* **Reset automatically:** Implement automatic context reset when refusals are detected320* **Fall back to another model:** Configure [server-side fallback or the SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) so refused requests are retried on another Claude model instead of surfacing a refusal to the user321* **Redeem fallback credit on manual retries:** If you build the retry yourself, pass the refusal's [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) token so the retry doesn't pay the prompt-cache cost twice322* **Provide custom messaging:** Create user-friendly messages for better UX when refusals occur323* **Track refusal patterns:** Monitor refusal frequency to identify potential issues with your prompts324325## Migration notes326327If you built refusal handling when this feature first shipped, or you're adding it to an existing integration, check the following:328329* **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.330* **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](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the full response shape.331* **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](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), and redeem [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) when you build the retry yourself.332* **Check batch results for refusals.** A refused request in a [Message Batch](https://platform.claude.com/docs/en/build-with-claude/batch-processing) is returned as a succeeded result with `stop_reason`: `"refusal"`, not as an errored result.333* **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.334335## Next steps336337<CardGroup cols={2}>338  <Card title="Refusals and fallback" icon="arrows-clockwise" href="https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback">339    Retry refused requests on another Claude model, server-side or in your client.340  </Card>341342  <Card title="Stop reasons and fallback" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons">343    Every `stop_reason` value and how to handle it.344  </Card>345346  <Card title="Streaming messages" icon="lightning" href="https://platform.claude.com/docs/en/build-with-claude/streaming">347    Stream responses and read `stop_reason` from `message_delta` events as they arrive.348  </Card>349350  <Card title="Multilingual support" icon="text-aa" href="https://platform.claude.com/docs/en/build-with-claude/multilingual-support">351    Serve users across languages with Claude's cross-lingual capabilities.352  </Card>353</CardGroup>354
Files main
Menu

Theme