Verificações de prefixo em blocos de pensamento

Cada requisição que envia blocos de pensamento de volta a um modelo com pensamento preservado passa por uma “prefix check” (verificação de prefixo). Uma verificação de prefixo falha se system, tools ou uma mensagem anterior mudou depois que Claude produziu um bloco. Ela também falha se um bloco de pensamento entre outros foi deixado de fora ou movido.

Falhar na verificação de prefixo pode ou não resultar em um erro 400, dependendo do modelo, então trate os dois casos.

A quem a verificação de prefixo afeta

Você não tem nada a mudar se uma destas afirmações for verdadeira:

• Claude Code, claude.ai ou Claude Managed Agents gerencia o seu histórico de conversa.
• O Claude Agent SDK gerencia o histórico, e o prompt do sistema que você fornece ao SDK permanece o mesmo.
• O seu código segue os três hábitos de uma integração append-only, e nada reescreve as requisições dele no caminho.
• Você não chama nenhum modelo com pensamento preservado.

Se as suas requisições passam por uma biblioteca, proxy ou gateway, compare o que ele envia com o que você enviou. Se você opera um, consulte Bibliotecas, proxies e gateways para saber o que repassar.

O que deve permanecer igual, e por quê

Torne a sua integração “append-only” (somente acréscimo). Três hábitos fazem isso:

1. Envie cada turno do assistente de volta exatamente como a API o retornou, incluindo blocos de pensamento cujo texto está vazio.
2. Construa system e tools uma vez para cada conversa e envie essa cópia todas as vezes.
3. Coloque cada atualização em uma nova mensagem no final e deixe-a lá.

O raciocínio de cada bloco de pensamento trata exatamente do que veio antes dele: system, tools e cada mensagem anterior. Esse conteúdo é o prefixo do bloco, e é o que a verificação de prefixo compara.

A verificação de prefixo é semelhante ao cache de prompt, exceto que uma mudança torna inválido o pensamento posterior a ela, em vez de apenas perder o cache.

Considere um app que coloca a data de hoje no seu prompt do sistema. À meia-noite a data muda, e com ela o prefixo do pensamento que já está na conversa. Esse pensamento se torna inválido, e a próxima requisição pode falhar. Um app append-only mantém o prompt do sistema como estava e informa a nova data em uma mensagem no final.

Uma mudança torna inválido apenas o pensamento que já vem depois dela. O pensamento anterior a ela e o pensamento que Claude produz em seguida permanecem válidos.

Se o seu código altera o prompt do sistema, as ferramentas ou o histórico

Outras causas, como pular blocos de pensamento cujo texto está vazio ou reconstruir uma conversa salva, têm correções próprias: consulte Altere ferramentas ou instruções sem falhar na verificação de prefixo. Para encontrar a sua, peça a um agente que verifique o seu código.

O que cada modelo faz quando a verificação de prefixo falha

Na Claude API e em algumas plataformas de nuvem, o resultado de falhar na verificação de prefixo com prefix_mismatch_behavior omitido da requisição depende do modelo:

Onde a tabela diz “Possível erro 400”, há dois casos: uma requisição que falha na verificação de prefixo pode receber um erro 400 ou nenhum erro. Quando nenhum erro é retornado, os blocos que falharam chegam ao modelo. Claude os lê como qualquer outra entrada, você é cobrado por eles, e Claude trabalha a partir de um raciocínio sobre conteúdo que, desde então, mudou.

Nesses modelos, você pode verificar qual caso uma requisição recebe, mas trate os dois casos.

Itens de Message Batches que deixam prefix_mismatch_behavior omitido da requisição não recebem erro, e a API pode descartar os blocos que falharam.

Trate os dois casos

Para ter um único resultado em todas as requisições, torne a sua integração append-only ou defina prefix_mismatch_behavior. Caso contrário, o seu código deve lidar com os dois comportamentos.

• Append-only: com os três hábitos, o seu código não faz uma requisição falhar na verificação de prefixo.
• A configuração: com "error" em todas as requisições, cada falha é um erro 400, e você o captura no código.
• Os dois comportamentos: se você deixar a configuração omitida da requisição, capture o erro 400 e fique atento a pensamento que falhou na verificação de prefixo e chegou a Claude.

Após um erro 400, envie "drop_block" nas requisições posteriores dessa conversa para se recuperar. Isso tem um custo: consulte Quanto custa descartar pensamento. Não o envie em todas as suas conversas para esconder erros.

Detalhes técnicos

Como a verificação de prefixo funciona

Os modelos com pensamento preservado registram uma impressão digital do prefixo de cada bloco de pensamento em sua signature. A referência da API chama a verificação de prefixo de verificação de conversa, e o erro 400 diz que um bloco que falhou na verificação de prefixo is bound to a different conversation.

Quais modelos executam a verificação de prefixo

A verificação de prefixo é executada na Claude API e em algumas plataformas de nuvem. Ela verifica blocos de pensamento que um modelo com pensamento preservado produziu, em requisições a um desses modelos. Na Claude API, outros modelos, como Claude Opus 5, não a executam, e ela não abrange os blocos deles.

O que conta como uma mudança

• Cada bloco é verificado em relação ao seu próprio registro. A API compara o que está antes de um bloco nesta requisição com o que a assinatura dele registrou quando Claude o produziu. A sua última requisição não participa disso. A verificação de prefixo olha apenas para o conteúdo, não para sessões, IDs ou usuários. O mesmo conteúdo em uma nova requisição ou em uma bifurcação passa nela.
• A verificação de prefixo compara o que você enviou, não o que Claude leu. Compactação em um limite de tokens e edição de contexto alteram apenas o que Claude lê, então nunca contam. Após um bloco de compactação por limite, a API compara apenas as mensagens a partir desse bloco, mais system e tools. A compactação sob demanda tem condições próprias: consulte Condições para que o pensamento mantido permaneça válido. Para um arquivo enviado por URL e, na Claude API, para uma lista de ferramentas MCP, a API compara, em vez disso, o que ela buscou.
• O pensamento que você envia deve ser uma sequência ininterrupta. Blocos de pensamento não são comparados como conteúdo. Mas cada um que você envia, exceto o primeiro, deve ter o mesmo bloco de pensamento anterior que tinha quando Claude o produziu. Assim, você pode deixar de fora o mais antigo, o mais recente ou todos eles, mas não um no meio.

Uma mudança pode ser tão pequena quanto uma palavra da descrição de uma ferramenta. Alterar, inserir, mover ou excluir uma mensagem anterior conta, qualquer que seja o seu papel. O mesmo vale para alterar texto antes de um bloco de pensamento na própria mensagem dele.

O que não conta

Defina prefix_mismatch_behavior

O cabeçalho beta thinking-binding-controls-2026-08-01 adiciona a configuração thinking.block_binding.prefix_mismatch_behavior e o array input_transformations da resposta.

Blocos que falham na verificação de prefixo permanecem inválidos em todas as requisições posteriores que os enviam, enquanto a mudança estiver em vigor. A configuração atua apenas na requisição que a carrega. Com o pensamento desligado ("disabled" ou "between_tools"), enviá-la resulta em um erro 400 em todos os modelos.

A requisição a seguir define prefix_mismatch_behavior como "drop_block". Em um primeiro turno não há pensamento a enviar de volta, então input_transformations volta vazio:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Monitore o tráfego de produção

Com prefix_mismatch_behavior omitido da requisição, uma requisição que falha na verificação de prefixo pode não receber erro em alguns modelos. Os blocos de pensamento que falharam nela chegam, então, ao modelo. Para encontrar esses blocos no tráfego de produção, envie o cabeçalho beta thinking-binding-controls-2026-08-01, deixe a configuração omitida da requisição e registre em log o array input_transformations de cada resposta. O cabeçalho adiciona esse array e não altera o que o modelo recebe.

Cada um desses blocos recebe sua própria entrada thinking_mismatch_allowed nesse array. Uma entrada tem esta aparência:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Para encontrar a mudança, consulte Encontre o que seu código alterou.

Verifique qual caso você recebe

Em alguns modelos, uma requisição que falha na verificação de prefixo pode receber o erro 400 ou nenhum erro. Este teste mostra qual deles uma requisição recebe:

1. Pegue uma conversa que contenha um bloco de pensamento de um desses modelos. Altere ou adicione o prompt do sistema (system). O bloco então falha na verificação de prefixo, porque o prompt do sistema mudou depois que Claude produziu o bloco.
2. Envie-a ao mesmo modelo com o cabeçalho beta thinking-binding-controls-2026-08-01 e deixe prefix_mismatch_behavior omitido da requisição.

A resposta é uma destas:

• Um erro 400 que diz bound to a different conversation: A requisição recebeu o erro 400.
• Uma resposta 200 cujo array input_transformations tem entradas thinking_mismatch_allowed: A requisição não recebeu erro. Cada entrada nomeia um bloco de pensamento que falhou na verificação de prefixo e chegou a Claude.
• Uma resposta 200 cujo array input_transformations está vazio: Nenhum bloco falhou na verificação de prefixo, então o teste não mostra nada. Verifique se a conversa contém um bloco de pensamento desse modelo.

O resultado descreve aquela única requisição e não promete nada sobre as posteriores, então escreva o seu código para tratar os dois casos.

Próximos passos