Recusas e fallback

O Claude Fable 5 inclui classificadores de segurança que podem recusar uma requisiçã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 requisiçã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 requisições recusadas sejam automaticamente encaminhadas 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.

A lista completa de valores de stop_reason está em Motivos de parada e fallback. Detalhes sobre como requisições recusadas são cobradas, e como evitar pagar duas vezes pelo cache de prompt em uma nova tentativa, estão em Crédito de fallback. O helper do SDK que encapsula tudo isso está em Middleware do SDK. Para um exemplo completo de ponta a ponta, consulte o cookbook de fallback e cobrança.

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

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" }]
});

As seções abaixo 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. Seu campo category nomeia a área de política que acionou o classificador. Seu campo 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, e 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 requisiçã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ê, então você só precisa daquela página quando estiver construindo a nova tentativa por conta própria.

Fallback do lado do servidor

O fallback do lado do servidor repete uma requisiçã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 requisiçã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 requisiçã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 Models API.
• Cada entrada nomeia um model e pode sobrescrever max_tokens e thinking apenas para aquela tentativa.
• A requisição deve ser válida como uma requisição direta para cada modelo nomeado. Se um modelo de fallback não suportar um recurso que a requisição usa, a API rejeita a requisição de antemã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 a 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 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 à do 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:

{
  "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 abaixo cobre quais manter e quais descartar quando você ecoar o turno.

Streaming

Em uma requisição de streaming, a nova tentativa acontece no mesmo stream, e nada do que você já recebeu é invalidado. 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, o bloco fallback (um par comum de content_block_start e content_block_stop sem deltas) marca a fronteira, e 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. No caso de recusa no meio da saída, 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.

Em uma requisiçã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 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 requisições recusadas automaticamente, em qualquer plataforma. O middleware também envia o cabeçalho beta fallback-credit-2026-06-01 em cada requisição que ele trata, de modo que as novas tentativas são reprecificadas sem configuração por requisição.

Configurando

Passe o middleware para o construtor do cliente e compartilhe uma instância de BetaFallbackState entre as requisiçõ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 seus eventos 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 requisição para a próxima entrada.
• A resposta de recusa original é retornada apenas quando todos os modelos da lista recusaram. O middleware não lança 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 requisições posteriores.
• 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 requisições posteriores.
• O modelo que aceitou é registrado em BetaFallbackState, de modo que requisições subsequentes que compartilham o estado permanecem fixadas nele em vez de perguntar novamente a um modelo que recusou.

Recusas em Message Batches

Uma requisiçã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 requisiçã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 requisições diretas.

Armadilhas comuns

• Repita em um modelo diferente. Reenviar uma requisiçã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 requisiçã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 cada caminho de requisição. Handlers de retry, ramos de recuperação de erro e workers em segundo plano, todos precisam dele. Um handler que reemite uma requisição sem fallback perde a proteção exatamente nas requisições com maior probabilidade de precisar dela.
• Dê às chamadas de subagente 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 requisiçã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 requisição desprotegida. Quando você não puder confirmar que o fallback está ativo, configure-o em vez de assumir 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 a última), então 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