Rechazos y fallback

Claude Fable 5 incluye clasificadores de seguridad que pueden rechazar una solicitud. Cuando eso sucede, recibes una respuesta normal, no un error, con stop_reason: "refusal". Por lo general, aún puedes obtener una respuesta enviando la misma solicitud a otro modelo de Claude. Esta página te muestra cómo reconocer un rechazo y cómo configurar ese reintento.

Lee esta página cuando desarrolles con Claude Fable 5 y quieras que las solicitudes rechazadas pasen automáticamente a otro modelo. También aplica cuando acabas de ver "refusal" en una respuesta y quieres saber qué hacer a continuación.

La lista completa de valores de stop_reason está en Stop reasons y fallback. Los detalles sobre cómo se facturan las solicitudes rechazadas, y cómo evitar pagar dos veces por el almacenamiento en caché de prompts en un reintento, están en Crédito de fallback. El helper del SDK que encapsula todo esto está en Middleware del SDK. Para ver un ejemplo completo de principio a fin, consulta el cookbook de fallback y facturación.

La configuración más simple: nombra un modelo de fallback en la solicitud, y la API se encarga del reintento.

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

Las secciones siguientes cubren qué contiene una respuesta de rechazo, cuándo usar fallback del lado del servidor o del lado del cliente, y cómo se factura cada uno.

Cómo se ve un rechazo

Un rechazo es una respuesta HTTP 200 exitosa con stop_reason: "refusal":

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

El objeto stop_details explica el rechazo. Su campo category nombra el área de política que activó el clasificador. Su campo explanation es una descripción legible para humanos; el texto no es estable, así que muéstralo en lugar de analizarlo. Ambos campos son null cuando el rechazo no corresponde a una categoría con nombre, y null es un valor normal y permanente en lugar de un marcador de posición. stop_details en sí es null para todos los stop reasons distintos de refusal.

Un rechazo puede llegar antes de cualquier salida, o a mitad del stream después de una salida parcial. En cualquier caso, trata cualquier salida parcial como incompleta y descártala.

Elegir un enfoque de fallback

Hay tres formas de reintentar una solicitud rechazada en otro modelo. La correcta depende de dónde estés ejecutando y cuánto control necesites.

El fallback del lado del servidor y el middleware del SDK aplican el crédito de fallback por ti, así que solo necesitas esa página cuando construyas el reintento tú mismo.

Fallback del lado del servidor

El fallback del lado del servidor reintenta una solicitud rechazada dentro de una sola llamada a la API. Nombras hasta tres modelos de fallback, y cuando Claude Fable 5 rechaza, la API ejecuta el siguiente modelo de la cadena con la misma solicitud. Recibes una sola respuesta que nombra el modelo que respondió, de modo que tu usuario obtiene una respuesta en un solo viaje de ida y vuelta.

Hacer la solicitud

Nombra los modelos de fallback en el parámetro fallbacks y envía el encabezado beta server-side-fallback-2026-06-01.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[{"model": "claude-opus-4-8"}],
    betas=["server-side-fallback-2026-06-01"],
)

# Una entrada fallback_message en usage.iterations indica que se ejecutó un modelo de respaldo;
# combínala con stop_reason para confirmar que el respaldo generó la respuesta.
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

print(
    json.dumps(
        {
            "stop_reason": response.stop_reason,
            "model": response.model,
            "served_by_fallback": served_by_fallback,
        }
    )
)

Algunas reglas aplican a la lista fallbacks:

• Las entradas se prueban en orden. Cada una debe ser distinta de las otras entradas y del modelo solicitado.
• Cada entrada debe ser uno de los destinos permitidos del modelo solicitado. Con el encabezado beta configurado, esa lista se publica como allowed_fallback_models en la entrada del modelo en la Models API.
• Cada entrada nombra un model y puede sobrescribir max_tokens y thinking solo para ese intento.
• La solicitud debe ser válida como solicitud directa a cada modelo nombrado. Si un modelo de fallback no admite una función que la solicitud usa, la API rechaza la solicitud de antemano.
• Solo un rechazo del clasificador de seguridad activa el fallback. Un límite de velocidad, sobrecarga o error del servidor en el modelo solicitado se te devuelve tal cual.

Qué contiene la respuesta

La respuesta se ve como cualquier otro mensaje, con dos adiciones:

• El campo model de nivel superior reporta el modelo que produjo el mensaje devuelto, ya sea el modelo solicitado o un fallback.
• Un bloque de contenido fallback marca cada punto en content donde la salida de un modelo da paso a la del siguiente: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}. from.model repite la cadena de modelo que enviaste cuando el salto que rechaza es el modelo solicitado. to.model es siempre el ID resuelto del modelo que continúa.

En un rechazo antes de cualquier salida, el bloque fallback es el primer bloque de contenido:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "fallback",
      "from": { "model": "claude-fable-5" },
      "to": { "model": "claude-opus-4-8" }
    },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

El array usage.iterations registra cada intento. Un modelo que rechazó aparece como una entrada message ordinaria, y el modelo que atendió el turno aparece como una entrada fallback_message. Si todos los modelos de la cadena rechazan, la respuesta es el rechazo del último modelo, con una entrada message para cada salto anterior y una entrada fallback_message para el último.

Continuar la conversación

En el siguiente turno, envía el contenido del asistente de vuelta tal como lo recibiste. Después de un fallback a mitad de la salida, content puede incluir tipos de bloque que el modelo que rechazó produjo antes del traspaso; la tabla siguiente cubre cuáles conservar y cuáles descartar cuando repitas el turno.

Streaming

En una solicitud con streaming, el reintento ocurre en el mismo stream, y nada de lo que ya has recibido se invalida. Cuando el rechazo ocurre antes de cualquier salida, message_start nombra el modelo de fallback y el bloque fallback es el primer bloque de contenido; como message_start espera a que el intento de fallback comience, el tiempo hasta el primer byte incluye el intento rechazado. Cuando el rechazo ocurre a mitad de la salida, el bloque de contenido abierto se cierra, el bloque fallback (un par ordinario de content_block_start y content_block_stop sin deltas) marca el límite, y el modelo de fallback continúa desde la salida parcial. Solo los bloques text de la salida parcial se pasan al modelo de fallback como contexto; los otros tipos de bloque permanecen en content. En el caso de mitad de salida, message_start ya nombró el modelo solicitado, así que lee el modelo que atiende desde el to.model del bloque fallback y desde la entrada fallback_message en el usage.iterations del message_delta final.

En una solicitud sin streaming, un rechazo a mitad de la salida se comporta de manera diferente: la respuesta omite la salida parcial del modelo rechazado, y el modelo de fallback responde desde cero. El resultado se ve como un rechazo antes de cualquier salida, con el bloque fallback primero. El intento rechazado y sus tokens de salida aún aparecen en usage.iterations.

Fallback del lado del cliente con el middleware del SDK

Los SDKs de TypeScript, Python, Go, Java y C# incluyen un middleware de fallback por rechazo. Lo configuras una vez en el cliente con tu lista de modelos de fallback. Las llamadas a través de client.beta.messages entonces reintentan solicitudes rechazadas automáticamente, en cualquier plataforma. El middleware también envía el encabezado beta fallback-credit-2026-06-01 en cada solicitud que maneja, así que los reintentos se retarifican sin configuración por solicitud.

Configurarlo

Pasa el middleware al constructor del cliente, y comparte una instancia de BetaFallbackState entre las solicitudes de una conversación.

# Ante un rechazo, el middleware reintenta con el modelo de respaldo indicado y
# envía automáticamente el encabezado beta de crédito de respaldo en cada solicitud que gestiona.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# Streaming: ante un rechazo, el middleware reintenta con el modelo de respaldo y
# empalma sus eventos en el stream abierto.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for event in stream:
        if event.type == "text":
            print(event.text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Sin streaming: reutilizar el estado mantiene la conversación fijada.
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")

Cómo se comporta

• Los reintentos recorren tu lista de fallback en orden. Un modelo de fallback que a su vez rechaza pasa la solicitud a la siguiente entrada.
• La respuesta de rechazo original se devuelve solo cuando todos los modelos de la lista han rechazado. El middleware no genera un error por ello.
• Los bloques de thinking de Claude Fable 5 se manejan por ti: el middleware los elimina del reintento y los gestiona en el historial de conversación en solicitudes posteriores.
• Las respuestas atendidas a través del middleware incluyen un bloque de contenido fallback en cada límite de modelo, igual que las respuestas de fallback del lado del servidor. El middleware gestiona esos bloques por ti en solicitudes posteriores.
• El modelo que aceptó se registra en BetaFallbackState, así que las solicitudes de seguimiento que comparten el estado permanecen fijadas a él en lugar de volver a preguntar a un modelo que rechazó.

Rechazos en Message Batches

Una solicitud rechazada en un Message Batch regresa como result.type: "succeeded" con stop_reason: "refusal". El campo stop_details puede ser null en los resultados de batch, así que detecta rechazos verificando stop_reason directamente.

El fallback del lado del servidor no está disponible para batches (una solicitud de batch que incluye fallbacks produce un resultado con error por elemento). Para reintentar elementos de batch rechazados:

1. Recopila los elementos rechazados de los resultados.
2. Elimina los bloques de thinking de Claude Fable 5 de cualquier historial de múltiples turnos.
3. Reenvíalos en un modelo de fallback como un nuevo batch o como solicitudes directas.

Errores comunes

• Reintenta en un modelo diferente. Reenviar una solicitud rechazada al mismo modelo generalmente produce otro rechazo. Dirige el reintento al modelo de fallback.
• Presupuesta reintentos por solicitud, no por turno ni por sesión. Un solo turno puede producir varios rechazos, por ejemplo un agente más sus subagentes.
• Configura fallback en cada ruta de solicitud. Los manejadores de reintentos, las ramas de recuperación de errores y los workers en segundo plano lo necesitan todos. Un manejador que reemite una solicitud sin fallback pierde la protección exactamente en las solicitudes que más probablemente la necesiten.
• Da a las llamadas de subagentes su propio fallback. El parámetro fallbacks no se propaga a las llamadas de modelo hechas desde dentro de la ejecución de herramientas.
• Haz que el fallback sea una propiedad de la solicitud, no del estado ambiental. Una bandera compartida, un valor de configuración en caché o un interruptor global pueden desincronizarse y dejar silenciosamente una solicitud sin protección. Cuando no puedas confirmar que el fallback está activo, configúralo en lugar de asumir que está activado.
• Instrumenta los rechazos como su propia señal. Un rechazo es un HTTP 200, así que el monitoreo basado en tasas de error o respuestas 5xx nunca lo ve. Emite un evento por rechazo y uno por respuesta atendida por fallback (la entrada fallback_message en usage.iterations marca esta última), luego alerta sobre la brecha entre los dos conteos.
• Ramifica según stop_reason, no según stop_details ni content. stop_details es informativo y puede ser null en un rechazo. Verifica que stop_reason sea igual a "refusal" directamente.

Próximos pasos