Recusas e fallback

Claude Fable 5 e Claude Opus 5 incluem 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 você construir sobre Claude Fable 5 ou Claude Opus 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 em seguida.

Páginas relacionadas:

• Stop reasons 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 "prompt caching" (cache de prompt) em uma nova tentativa.
• Middleware do SDK: o auxiliar do SDK que encapsula tudo isso.
• Cookbook de fallback e cobrança: um exemplo completo de ponta a ponta.

A configuração mais simples, em beta na Claude API: defina fallbacks como "default", e a API repete uma solicitação recusada no modelo de fallback que a Anthropic recomenda para sua categoria de recusa. Para categorias sem fallback recomendado, a recusa é mantida.

client = Anthropic()

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

As seções a seguir cobrem 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.
• 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 stop reasons que não sejam refusal.

Uma recusa pode chegar antes de qualquer saída, ou no meio do stream após uma 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 correta 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 você mesmo constrói a nova tentativa.



Fallback do lado do servidor

O fallback do lado do servidor repete uma solicitação recusada dentro de uma única chamada de API. No modo padrão, quando o modelo primário recusa e a categoria de recusa tem um fallback recomendado, a API executa a mesma solicitação no modelo que a Anthropic recomenda para essa categoria. Você pode, em vez disso, nomear até três modelos de fallback próprios (abaixo). De qualquer forma, você recebe de volta uma 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

Defina o parâmetro fallbacks como a string "default" e envie o cabeçalho beta server-side-fallback-2026-07-01. A API então aplica o roteamento padrão definido pelo servidor para o modelo solicitado, que seleciona um modelo de fallback recomendado com base na categoria de recusa que o classificador reporta, de modo que solicitações recusadas sejam atendidas sem que você mantenha uma lista de modelos conforme as recomendações mudam.

client = Anthropic()

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

# Uma entrada fallback_message em usage.iterations significa 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,
        }
    )
)

A Anthropic define salvaguardas para cada modelo individualmente e para cada categoria de política, de acordo com a capacidade do modelo: dependendo da categoria, uma solicitação sinalizada pode recorrer a um modelo menos capaz ou ser recusada. O modo "default" codifica essas recomendações por modelo e por categoria para você, de modo que uma solicitação recusada seja repetida no modelo que a Anthropic recomenda para essa categoria. Os fallbacks são visíveis de qualquer forma: a resposta nomeia o modelo que a atendeu, e o bloco de conteúdo fallback marca a transferência.

O roteamento é aplicado do lado do servidor e não é publicado por modelo na Models API. Para ver qual modelo atendeu uma solicitação recusada, verifique o campo model de nível superior da resposta e procure uma entrada fallback_message em usage.iterations, como fazem os exemplos desta página.

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á.



Nomeando seus próprios modelos de fallback

Em vez do roteamento padrão, você pode definir fallbacks como uma lista de até três modelos. Quando o modelo solicitado recusa, a API executa o próximo modelo da cadeia na mesma solicitação. Use esta forma quando quiser controlar exatamente quais modelos atendem solicitações recusadas, como fixar um modelo que sua aplicação qualificou.

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-07-01"],
)
print(response.model)

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 destinos permitidos do modelo solicitado. Com o cabeçalho beta definido, essa lista é publicada como allowed_fallback_models na entrada do modelo na Models API.
• Cada entrada nomeia um model e pode sobrescrever max_tokens, thinking, output_config e speed apenas para essa 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 de imediato.
• Assim como no modo padrão, 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á.

A forma de lista explícita também funciona sob o cabeçalho beta server-side-fallback-2026-06-01; o modo "default" não.

A resposta tem o mesmo formato em ambos os modos: o modelo que atendeu o turno aparece no campo model de nível superior, um bloco de conteúdo fallback marca a transferência, e usage.iterations registra cada tentativa.



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 reporta o modelo que produziu a mensagem retornada, seja ele 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 ao próximo: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model ecoa a string de modelo que você enviou quando o salto 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. Por exemplo, quando o roteamento padrão seleciona Claude Opus 4.8 para a categoria da recusa:

{
  "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 salto anterior e uma entrada fallback_message para o último.



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 a seguir cobre quais manter e quais descartar quando você ecoa o turno.



Streaming

Em uma solicitação de 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 o início da tentativa de fallback, 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 a fronteira.
• 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 que recusou, 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 output_tokens ainda aparecem em usage.iterations.



Fallback do lado do cliente com o middleware do SDK

Todo SDK da Anthropic inclui um middleware de fallback de recusa. Você o configura uma vez no cliente com sua lista de modelos de fallback. 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-07-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.

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# Em caso de recusa, o middleware tenta novamente no modelo de fallback listado e
# envia automaticamente o header beta de crédito de fallback em cada requisição que ele trata.
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 text in stream.text_stream:
        print(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.
• Quando todos os modelos da lista recusaram, o middleware retorna a recusa final (a resposta de recusa do último modelo) em vez de lançar um erro.
• Blocos de thinking do Claude Fable 5 passam sem alteração: cada nova tentativa reenvia o corpo da sua solicitação original, e os únicos blocos que o middleware remove do histórico da conversa em solicitações posteriores são os blocos de fronteira fallback que ele mesmo adicionou.
• Respostas atendidas através do middleware incluem um bloco de conteúdo fallback em cada fronteira 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, então 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". Os resultados de lote carregam o mesmo objeto stop_details que as respostas síncronas, então você pode detectar recusas através de stop_reason ou de stop_details.type. Uma diferença: recusas em lote não geram créditos de fallback, então stop_details em um resultado de lote nunca inclui um fallback_credit_token.

O fallback do lado do servidor não está disponível para lotes (uma solicitação de lote que inclui fallbacks produz um resultado com erro por item). Para repetir itens de lote 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 lote 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 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. Manipuladores de nova tentativa, ramificações de recuperação de erro e workers em segundo plano precisam dele. Um manipulador que reemite uma solicitação sem fallback perde a proteção exatamente nas solicitações que mais provavelmente precisam 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 um estado ambiente. Uma flag compartilhada, um valor de configuração em cache ou um alternador global podem ficar fora 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 o monitoramento construído sobre 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 ou stop_details.type, não em content ou nos campos internos de stop_details. O objeto stop_details está sempre presente em uma recusa, mas seus campos category e explanation podem ser null. Verifique diretamente se stop_reason é igual a "refusal".



Próximos passos