Recusas em streaming

A partir dos modelos Claude 4, as respostas em streaming da API do Claude retornam stop_reason: "refusal" quando classificadores de streaming intervêm para lidar com possíveis violações de políticas. Este novo recurso de segurança ajuda a manter a conformidade de conteúdo durante o streaming em tempo real.

Para saber mais sobre recusas acionadas pelos filtros de segurança da API para Claude Sonnet 4.5, consulte Understanding Sonnet 4.5's API Safety Filters.

Formato de resposta da API

Quando classificadores de streaming detectam conteúdo que viola as políticas da Anthropic, a API retorna esta resposta:

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

Nenhuma mensagem de recusa adicional é incluída. Você deve lidar com a resposta e fornecer mensagens apropriadas voltadas para o usuário.

Redefinir contexto após recusa

Quando você recebe stop_reason: refusal, você deve redefinir o contexto da conversa removendo ou atualizando a volta que foi recusada antes de continuar. Tentar continuar sem redefinir resultará em recusas contínuas.

As métricas de uso ainda são fornecidas na resposta para fins de faturamento, mesmo quando a resposta é recusada.

Você será cobrado pelos tokens de saída até a recusa.

Se você encontrar motivos de parada refusal com frequência ao usar Claude Sonnet 4.5 ou Opus 4.1, você pode tentar atualizar suas chamadas de API para usar Haiku 4.5 (claude-haiku-4-5-20251001), que tem restrições de uso diferentes. Saiba mais sobre understanding Sonnet 4.5's API safety filters.

Guia de implementação

Aqui está como detectar e lidar com recusas de streaming em sua aplicação:

Tipos de recusa atuais

A API atualmente lida com recusas de três maneiras diferentes:

Tipo de Recusa	Formato de Resposta	Quando Ocorre
Recusas do classificador de streaming	`stop_reason`: `refusal`	Durante o streaming quando o conteúdo viola políticas
Validação de entrada e direitos autorais da API	Códigos de erro 400	Quando a entrada falha nas verificações de validação
Recusas geradas pelo modelo	Respostas de texto padrão	Quando o próprio modelo decide recusar

Futuras versões da API expandirão o padrão stop_reason: refusal para unificar o tratamento de recusas em todos os tipos.

Boas práticas

Monitore recusas: Inclua verificações de stop_reason: refusal em seu tratamento de erros
Redefina automaticamente: Implemente redefinição automática de contexto quando recusas forem detectadas
Forneça mensagens personalizadas: Crie mensagens amigáveis ao usuário para melhor UX quando recusas ocorrem
Rastreie padrões de recusa: Monitore a frequência de recusas para identificar possíveis problemas com seus prompts

Notas de migração

Modelos futuros expandirão este padrão para outros tipos de recusa
Planeje seu tratamento de erros para acomodar a unificação futura de respostas de recusa

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