Repository Public
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