Recusas e fallback

O Claude Fable 5 inclui classificadores de segurança que podem recusar uma solicitação. Quando isso acontece, você recebe uma resposta normal, não um erro, com stop_reason: "refusal". Normalmente, você ainda pode obter uma resposta enviando a mesma solicitação para outro modelo Claude. Esta página mostra como reconhecer uma recusa e como configurar essa nova tentativa.

Leia esta página quando estiver desenvolvendo com o Claude Fable 5 e quiser que solicitações recusadas sejam encaminhadas automaticamente para outro modelo. Ela também se aplica quando você acabou de ver "refusal" em uma resposta e quer saber o que fazer a seguir.

Páginas relacionadas:

• Motivos de parada e fallback: a lista completa de valores de stop_reason.
• Crédito de fallback: como solicitações recusadas são cobradas e como evitar pagar duas vezes pelo cache de prompt em uma nova tentativa.
• Middleware do SDK: o helper do SDK que encapsula tudo isso.
• Cookbook de fallback e cobrança: um exemplo completo de ponta a ponta.

A configuração mais simples: nomeie um modelo de fallback na solicitação, e a API cuida da nova tentativa.

client = Anthropic()

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"],
)

As seções abaixo abordam o que uma resposta de recusa contém, quando usar fallback do lado do servidor ou do lado do cliente, e como cada um é cobrado.



Como é uma recusa

Uma recusa é uma resposta HTTP 200 bem-sucedida com 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
  }
}

O objeto stop_details explica a recusa:

• category: nomeia a área de política que acionou o classificador.
• explanation: uma descrição legível por humanos. O texto não é estável, então exiba-o em vez de analisá-lo programaticamente.
• Ambos os campos são null quando a recusa não corresponde a uma categoria nomeada. Esse null é um valor normal e permanente, não um placeholder.
• O próprio stop_details é null para todos os motivos de parada que não sejam refusal.

Uma recusa pode chegar antes de qualquer saída ou no meio do stream, após saída parcial. Em ambos os casos, trate qualquer saída parcial como incompleta e descarte-a.



Escolhendo uma abordagem de fallback

Há três maneiras de repetir uma solicitação recusada em outro modelo. A escolha certa depende de onde você está executando e de quanto controle você precisa.

O fallback do lado do servidor e o middleware do SDK aplicam o crédito de fallback para você. Você só precisa da página Crédito de fallback quando constrói a nova tentativa por conta própria.



Fallback do lado do servidor

O fallback do lado do servidor repete uma solicitação recusada dentro de uma única chamada de API. Você nomeia até três modelos de fallback e, quando o Claude Fable 5 recusa, a API executa o próximo modelo da cadeia na mesma solicitação. Você recebe de volta uma única resposta que nomeia o modelo que respondeu, de modo que seu usuário obtém uma resposta em uma única ida e volta.



Fazendo a solicitação

Nomeie os modelos de fallback no parâmetro fallbacks e envie o cabeçalho 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"],
)

# Uma entrada fallback_message em usage.iterations indica que um modelo de fallback foi executado;
# combine-a com stop_reason para confirmar que o fallback atendeu à resposta.
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,
        }
    )
)

Algumas regras se aplicam à lista fallbacks:

• As entradas são tentadas em ordem. Cada uma deve ser distinta das outras entradas e do modelo solicitado.
• Cada entrada deve ser um dos alvos permitidos do modelo solicitado. Com o cabeçalho beta definido, essa lista é publicada como allowed_fallback_models na entrada do modelo na API de Modelos.
• Cada entrada nomeia um model e pode sobrescrever max_tokens e thinking apenas para aquela tentativa.
• A solicitação deve ser válida como uma solicitação direta para cada modelo nomeado. Se um modelo de fallback não suportar um recurso que a solicitação usa, a API rejeita a solicitação antecipadamente.
• Apenas uma recusa do classificador de segurança aciona o fallback. Um limite de taxa, sobrecarga ou erro de servidor no modelo solicitado é retornado para você como está.



O que a resposta contém

A resposta se parece com qualquer outra mensagem, com duas adições:

• O campo model de nível superior informa o modelo que produziu a mensagem retornada, seja o modelo solicitado ou um fallback.
• Um bloco de conteúdo fallback marca cada ponto em content onde a saída de um modelo dá lugar à do próximo: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model ecoa a string de modelo que você enviou quando a etapa que recusou é o modelo solicitado.
  • to.model é sempre o ID resolvido do modelo que continua.

Em uma recusa antes de qualquer saída, o bloco fallback é o primeiro bloco de conteúdo:

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

O array usage.iterations registra cada tentativa. Um modelo que recusou aparece como uma entrada message comum, e o modelo que atendeu o turno aparece como uma entrada fallback_message. Se todos os modelos da cadeia recusarem, a resposta é a recusa do último modelo, com uma entrada message para cada etapa anterior e uma entrada fallback_message para a última.



Continuando a conversa

No próximo turno, envie o conteúdo do assistente de volta como você o recebeu. Após um fallback no meio da saída, content pode incluir tipos de bloco que o modelo que recusou produziu antes da transferência; a tabela abaixo indica quais manter e quais descartar ao ecoar o turno.



Streaming

Em uma solicitação com streaming, a nova tentativa acontece no mesmo stream, e nada do que você já recebeu é invalidado. O que você vê depende de quando a recusa acontece.

Quando a recusa acontece antes de qualquer saída:

• message_start nomeia o modelo de fallback, e o bloco fallback é o primeiro bloco de conteúdo.
• Como message_start espera a tentativa de fallback começar, o tempo até o primeiro byte inclui a tentativa recusada.

Quando a recusa acontece no meio da saída:

• O bloco de conteúdo aberto é fechado, e o bloco fallback (um par comum de content_block_start e content_block_stop sem deltas) marca o limite.
• O modelo de fallback continua a partir da saída parcial. Apenas os blocos text da saída parcial são passados ao modelo de fallback como contexto; outros tipos de bloco permanecem em content.
• message_start já nomeou o modelo solicitado, então leia o modelo que está atendendo a partir do to.model do bloco fallback e da entrada fallback_message em usage.iterations do message_delta final.



Respostas sem streaming

Em uma solicitação sem streaming, uma recusa no meio da saída se comporta de forma diferente: a resposta omite a saída parcial do modelo recusado, e o modelo de fallback responde do zero. O resultado se parece com uma recusa antes de qualquer saída, com o bloco fallback primeiro. A tentativa recusada e seus tokens de saída ainda aparecem em usage.iterations.



Fallback do lado do cliente com o middleware do SDK

Os SDKs de TypeScript, Python, Go, Java e C# incluem um middleware de fallback de recusa. Você o configura uma vez no cliente com sua lista de modelos de fallback. As chamadas através de client.beta.messages então repetem solicitações recusadas automaticamente, em qualquer plataforma. O middleware também envia o cabeçalho beta fallback-credit-2026-06-01 em cada solicitação que ele trata, de modo que as novas tentativas são reprecificadas sem configuração por solicitação.



Configurando

Passe o middleware para o construtor do cliente e compartilhe uma instância de BetaFallbackState entre as solicitações de uma conversa.

# Em caso de recusa, o middleware tenta novamente no modelo de fallback listado e
# envia automaticamente o cabeçalho beta de crédito de fallback em cada requisição que processa.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

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

# Streaming: em caso de recusa, o middleware tenta novamente no modelo de fallback e
# insere os eventos dele no stream aberto.
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}")

# Sem streaming: reutilizar o estado mantém a conversa fixada.
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}")



Como ele se comporta

• As novas tentativas percorrem sua lista de fallback em ordem. Um modelo de fallback que também recusa passa a solicitação para a próxima entrada.
• A resposta de recusa original é retornada apenas quando todos os modelos da lista recusaram. O middleware não gera um erro para isso.
• Blocos de thinking do Claude Fable 5 são tratados para você: o middleware os remove da nova tentativa e os gerencia no histórico da conversa em solicitações posteriores.
• Respostas atendidas através do middleware incluem um bloco de conteúdo fallback em cada limite de modelo, da mesma forma que as respostas de fallback do lado do servidor. O middleware gerencia esses blocos para você em solicitações posteriores.
• O modelo que aceitou é registrado em BetaFallbackState, de modo que solicitações subsequentes que compartilham o estado permanecem fixadas nele em vez de perguntar novamente a um modelo que recusou.



Recusas em Message Batches

Uma solicitação recusada em um Message Batch retorna como result.type: "succeeded" com stop_reason: "refusal". O campo stop_details pode ser null em resultados de batch, então detecte recusas verificando stop_reason diretamente.

O fallback do lado do servidor não está disponível para batches (uma solicitação de batch que inclui fallbacks produz um resultado com erro por item). Para repetir itens de batch recusados:

1. Colete os itens recusados dos resultados.
2. Remova os blocos de thinking do Claude Fable 5 de quaisquer históricos de múltiplos turnos.
3. Reenvie-os em um modelo de fallback como um novo batch ou como solicitações diretas.



Armadilhas comuns

• Repita em um modelo diferente. Reenviar uma solicitação recusada para o mesmo modelo geralmente resulta em outra recusa. Direcione a nova tentativa para o modelo de fallback.
• Orce as novas tentativas por solicitação, não por turno ou por sessão. Um único turno pode produzir várias recusas, por exemplo, um agente mais seus subagentes.
• Configure o fallback em todos os caminhos de solicitação. Handlers de retry, ramificações de recuperação de erro e workers em segundo plano, todos precisam dele. Um handler que reemite uma solicitação sem fallback perde a proteção exatamente nas solicitações com maior probabilidade de precisar dela.
• Dê às chamadas de subagentes seu próprio fallback. O parâmetro fallbacks não se propaga para chamadas de modelo feitas de dentro da execução de ferramentas.
• Faça do fallback uma propriedade da solicitação, não de estado ambiente. Uma flag compartilhada, valor de configuração em cache ou toggle global pode sair de sincronia e silenciosamente deixar uma solicitação desprotegida. Quando você não puder confirmar que o fallback está ativo, configure-o em vez de presumir que está ligado.
• Instrumente recusas como seu próprio sinal. Uma recusa é um HTTP 200, então monitoramento baseado em taxas de erro ou respostas 5xx nunca a vê. Emita um evento por recusa e um por resposta atendida por fallback (a entrada fallback_message em usage.iterations marca esta última), depois alerte sobre a diferença entre as duas contagens.
• Ramifique com base em stop_reason, não em stop_details ou content. stop_details é informativo e pode ser null em uma recusa. Verifique se stop_reason é igual a "refusal" diretamente.



Próximos passos