Maneja rechazos en streaming

A partir de los modelos Claude 4, las respuestas en streaming de la API de Claude devuelven stop_reason: "refusal" cuando los clasificadores de streaming intervienen para manejar posibles violaciones de políticas. Esta característica de seguridad ayuda a mantener el cumplimiento del contenido durante el streaming en tiempo real.



Formato de respuesta de la API

Cuando los clasificadores de streaming detectan contenido que viola las políticas de Anthropic, la API devuelve esta respuesta:

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

En el flujo de eventos, stop_details llega en el evento message_delta junto con stop_reason.



Restablece el contexto después de un rechazo

Cuando recibes stop_reason: refusal, debes restablecer el contexto de la conversación antes de continuar. Puedes eliminar o reformular el turno que desencadenó el rechazo, o borrar el historial de la conversación por completo. Intentar continuar sin restablecer resultará en rechazos continuos.



Guía de implementación

Así es como puedes detectar y manejar rechazos en streaming en tu aplicación:

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:
            # Verificar si hay un rechazo en el delta del mensaje
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")



Tipos de rechazo actuales

La API actualmente maneja los rechazos de tres maneras diferentes:



Mejores prácticas

• Monitorea los rechazos: Incluye verificaciones de stop_reason: refusal en tu manejo de errores
• Restablece automáticamente: Implementa el restablecimiento automático del contexto cuando se detecten rechazos
• Recurre a otro modelo: Configura el respaldo del lado del servidor o el middleware del SDK para que las solicitudes rechazadas se reintenten en otro modelo de Claude en lugar de mostrar un rechazo al usuario
• Canjea el crédito de respaldo en reintentos manuales: Si construyes el reintento tú mismo, pasa el token de crédito de respaldo del rechazo para que el reintento no pague dos veces el costo de la caché de prompts
• Proporciona mensajes personalizados: Crea mensajes amigables para el usuario para una mejor experiencia de usuario cuando ocurran rechazos
• Rastrea patrones de rechazo: Monitorea la frecuencia de rechazos para identificar posibles problemas con tus prompts



Notas de migración

Si construiste el manejo de rechazos cuando esta característica se lanzó por primera vez, o la estás agregando a una integración existente, verifica lo siguiente:

• Los rechazos son respuestas, no errores. Un rechazo llega como una respuesta HTTP 200 exitosa con stop_reason: "refusal", por lo que el monitoreo basado solo en tasas de error no lo detectará. Rastrea los rechazos como su propia señal.
• Los rechazos incluyen detalles estructurados. En cada modelo, un rechazo también incluye un objeto stop_details que identifica la categoría de política detrás de la negativa. Consulta Rechazos y respaldo para ver la forma completa de la respuesta.
• Reintenta en un modelo diferente. Reenviar una solicitud rechazada al mismo modelo generalmente resulta en otro rechazo. En lugar de solo restablecer el contexto, reintenta en un modelo de respaldo con respaldo del lado del servidor, el middleware del SDK o un reintento manual, y canjea el crédito de respaldo cuando construyas el reintento tú mismo.
• Verifica los resultados de lotes en busca de rechazos. Una solicitud rechazada en un Message Batch se devuelve como un resultado exitoso con stop_reason: "refusal", no como un resultado con error.
• Centraliza el manejo en stop_reason. La API continúa consolidando el manejo de rechazos en torno a stop_reason: "refusal", así que ramifica según la razón de detención en lugar de según el comportamiento específico del modelo.



Próximos pasos