Manejar rechazos en streaming

A partir de los modelos Claude 4, las respuestas de streaming de la API de Claude devuelven stop_reason: "refusal" cuando los clasificadores de streaming intervienen para manejar posibles violaciones de políticas. Esta función 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.

Restablecer 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 provocó el rechazo, o borrar por completo el historial de la conversación. Intentar continuar sin restablecer dará como resultado 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-5",
    ) as stream:
        for event in stream:
            # Comprueba 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 formas 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 del almacenamiento en caché de prompts
• Proporciona mensajes personalizados: Crea mensajes amigables para el usuario para una mejor experiencia cuando ocurran rechazos
• Rastrea los 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 función se lanzó por primera vez, o lo 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 un monitoreo basado únicamente en tasas de error no lo detectará. Rastrea los rechazos como su propia señal.
• Los rechazos incluyen detalles estructurados. En todos los modelos, 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. Volver a enviar una solicitud rechazada al mismo modelo generalmente da como resultado 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.
• Revisa 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 el motivo de detención en lugar de según el comportamiento específico del modelo.

Próximos pasos