Solução de problemas do pensamento

Esta página aborda as falhas mais comuns ao configurar o pensamento ou ao fazer o "round-tripping" (ida e volta) de "thinking blocks" (blocos de pensamento), ou seja, enviar os blocos de pensamento retornados de volta em solicitações posteriores. A primeira seção relaciona cada modelo às configurações de pensamento que ele suporta e às que ele rejeita. Cada uma das seções seguintes começa por um sintoma que você observa, para que você possa associar uma mensagem de erro ou uma resposta inesperada diretamente à sua causa e à sua correção. Para saber como o pensamento funciona, consulte a visão geral de Pensamento.

Suporte a pensamento, padrões e configurações rejeitadas por modelo

A maioria dos erros de configuração de pensamento é uma incompatibilidade entre o valor de thinking.type na solicitação e o que o modelo suporta. Na maioria dos modelos, o pensamento é executado como thinking: {type: "adaptive"}, e muitos o têm ativado por padrão. Alguns modelos anteriores usam, em vez disso, o "extended thinking" (pensamento estendido), um modo manual legado configurado como thinking: {type: "enabled", budget_tokens: N}.

O "extended thinking" (pensamento estendido) (thinking.type: "enabled" com budget_tokens) está descontinuado nos modelos Claude 4.6 (requisições que o utilizam ainda são bem-sucedidas). Os modelos Claude 4.7 e posteriores não o suportam e rejeitam requisições que o utilizam, retornando um erro 400. Nos modelos Claude 4.5 e anteriores que suportam pensamento, o pensamento estendido é o único modo de pensamento disponível. O Claude Mythos Preview suporta ambos os modos. Onde ambos os modos estiverem disponíveis, use o pensamento adaptativo em vez disso.

A tabela lista o que cada modelo suporta, qual é o seu padrão e quais valores de thinking.type ele rejeita com um erro 400; qualquer valor não listado como rejeitado é aceito. Apenas o Claude Sonnet 5.5 aceita "between_tools", e ele recebe esse valor no lugar de "disabled".

¹ enabled e budget_tokens ainda funcionam nesses modelos, mas estão descontinuados; use o pensamento adaptativo em vez disso.
² Claude Opus 5 e Claude Haiku 5.5 aceitam "disabled" com effort high ou inferior; combiná-lo com effort xhigh ou max retorna um erro 400. No Claude Opus 5, essa restrição é aplicada em cada solicitação. No Claude Haiku 5.5, um effort por mensagem que difere do nível em vigor também retorna um erro 400.
³ Claude Sonnet 5.5 aceita "between_tools" com effort high ou inferior. Combiná-lo com effort xhigh ou max retorna um erro 400, assim como um effort por mensagem que difere do nível em vigor.

Modelos marcados como Sempre ativado não podem desativar o pensamento. Modelos marcados como Ativado pensam por padrão. Claude Opus 5, Claude Sonnet 5 e Claude Haiku 5.5 aceitam thinking: {type: "disabled"}. No Claude Sonnet 5.5, envie thinking: {type: "between_tools"} para desativar o pensamento antecipado.

Os modelos Claude 4 anteriores (Claude Opus 4.1, Claude Sonnet 4 e Claude Opus 4) suportam apenas o pensamento estendido. Consulte Descontinuações de modelos para saber sobre sua disponibilidade. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 não estão disponíveis sob retenção zero de dados, a menos que expressamente autorizado pela Anthropic.

Um erro 400 informa que "thinking.type.enabled" não é suportado

A solicitação falha com um erro 400 cuja mensagem diz:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Isso acontece porque o modelo solicitado removeu o pensamento estendido (consulte a tabela de configuração por modelo).

Altere a solicitação para thinking: {type: "adaptive"} e controle a profundidade do pensamento com effort em vez de budget_tokens. Migrando para o pensamento adaptativo explica a conversão passo a passo.

Um erro 400 após enviar thinking: {type: "disabled"}

A solicitação falha com um erro 400. No Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5 e Claude Mythos 5, a mensagem diz:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

No Claude Mythos Preview, o único desses modelos que aceita pensamento estendido, a mensagem diz:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

Isso acontece porque o pensamento está sempre ativado em todos esses modelos (consulte a tabela de configuração por modelo).

Omita o parâmetro thinking; esses modelos pensam sem nenhuma configuração. Se o seu objetivo era manter o texto do pensamento fora das respostas, use display: "omitted" em vez de desativar o pensamento; consulte Controlando a exibição do pensamento.

Um erro 400 com "disabled" também pode ocorrer no Claude Opus 5 e no Claude Haiku 5.5, que aceitam thinking: {type: "disabled"} apenas com effort high ou inferior: combiná-lo com effort xhigh ou max é rejeitado. Reduza o nível de effort ou defina thinking como {"type": "adaptive"}.

No Claude Sonnet 5.5, thinking: {type: "disabled"} retorna um erro 400 em todos os níveis de effort. A mensagem diz:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Para desativar o pensamento antecipado no Claude Sonnet 5.5, envie thinking: {type: "between_tools"} em vez disso, com effort high ou inferior.

Um erro 400 informa que "thinking.type.between_tools" não é suportado

A solicitação falha com um erro 400 cuja mensagem diz:

"thinking.type.between_tools" is not supported for this model.

Isso acontece porque somente o Claude Sonnet 5.5 aceita thinking: {type: "between_tools"} (consulte a tabela de configuração por modelo).

Envie between_tools somente para o Claude Sonnet 5.5. Em outros modelos, omita thinking ou use um valor de thinking.type que a tabela não liste como rejeitado.

Um erro 400 informa que um nível de effort não é suportado quando o pensamento está desativado

No Claude Sonnet 5.5, uma solicitação com thinking: {type: "between_tools"} com effort xhigh ou max falha com um erro 400 cuja mensagem diz:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

Isso acontece porque o Claude Sonnet 5.5 aceita between_tools apenas com effort high ou inferior. A mensagem diz que o pensamento está desativado porque between_tools não tem pensamento antecipado, mesmo que a solicitação não tenha enviado "disabled". A mensagem nomeia o nível que a solicitação enviou.

Reduza o effort para high ou inferior. Para executar com xhigh ou max, use o pensamento adaptativo: omita o campo thinking ou envie thinking: {"type": "adaptive"}. É isso que a mensagem quer dizer com "enable thinking". O Claude Sonnet 5.5 rejeita "enabled" com um erro 400.

O Claude Haiku 5.5 retorna a mesma mensagem quando uma solicitação envia thinking: {type: "disabled"} com effort xhigh ou max. Ele aceita "disabled" apenas com high ou inferior. Reduza o effort ou defina thinking como {"type": "adaptive"}.

Um erro 400 informa que o effort não pode mudar quando o pensamento está desativado

No Claude Sonnet 5.5, uma solicitação com thinking: {type: "between_tools"} cujo effort por mensagem altera o nível falha com um erro 400 cuja mensagem diz:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

A mensagem diz que o pensamento está desativado porque between_tools não tem pensamento antecipado. Com between_tools, o effort não pode mudar no meio da conversa: um output_config.effort por mensagem que difere do nível em vigor retorna um erro 400. messages.N é a posição da mensagem que definiu o novo nível.

Remova esse effort por mensagem ou defina-o para o nível em vigor. Para variar o effort a cada turno, use o pensamento adaptativo: omita o campo thinking ou envie thinking: {"type": "adaptive"}. É isso que a mensagem quer dizer com "enable thinking".

O Claude Haiku 5.5 retorna a mesma mensagem quando uma solicitação com thinking: {type: "disabled"} define um effort por mensagem que difere do nível em vigor. Remova esse effort por mensagem ou defina thinking como {"type": "adaptive"} para variar o effort a cada turno.

Um erro 400 informa que o pensamento adaptativo não é suportado

A solicitação falha com um erro 400 cuja mensagem diz:

adaptive thinking is not supported on this model

Isso acontece porque o modelo suporta somente o pensamento estendido (consulte a tabela de configuração por modelo).

Use thinking: {type: "enabled", budget_tokens: N} em vez disso; consulte Pensamento estendido para ver a configuração.

Um erro 400 informa que os blocos de pensamento não podem ser modificados

Uma solicitação que retorna resultados de ferramentas falha com um erro 400 invalid_request_error cuja mensagem contém:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

Em conversas com múltiplos turnos e com "tool use" (uso de ferramentas), você envia as mensagens anteriores do assistente, incluindo seus blocos thinking e redacted_thinking, de volta para a API, e a API verifica se elas chegam sem modificações. Esse erro acontece quando a mensagem do assistente que você envia de volta difere daquela que a API retornou, na maioria das vezes porque seu código filtra os blocos de conteúdo por tipo e descarta os blocos redacted_thinking, ou reconstrói a mensagem do assistente em vez de reenviá-la como está.

Reenvie o turno do assistente exatamente como foi recebido, incluindo os blocos de pensamento. Consulte Preservando blocos de pensamento para ver as regras, e o exemplo completo de ida e volta em Pensamento em fluxos de trabalho com ferramentas e múltiplos turnos para ver o código correto em todos os SDKs.

Um erro 400 informa que a assinatura de um bloco de pensamento é inválida

Uma solicitação ao Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 ou Claude Haiku 5.5 que reenvia blocos de pensamento anteriores falha com um erro 400 invalid_request_error cuja mensagem diz:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Se a solicitação não enviou o cabeçalho beta thinking-binding-controls-2026-08-01, a mensagem acrescenta That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

A mensagem geralmente termina com uma frase que nomeia o que mudou: o prompt system, a lista tools, a primeira mensagem ou bloco que difere, conteúdo ausente ou novo, ou um bloco de pensamento anterior ausente ou fora de ordem. Essa frase é destinada a pessoas e logs. Sua redação pode mudar, então não faça correspondência com ela no código.

Se a mensagem terminar após Invalid `signature` in `thinking` block, a própria assinatura não foi verificada: ela foi truncada, alterada ou enviada de volta vazia, e prefix_mismatch_behavior não se aplica. Texto de pensamento editado retorna um erro diferente. Consulte Um erro 400 informa que os blocos de pensamento não podem ser modificados.

No Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5, a API aceita um bloco de pensamento reenviado apenas enquanto o prompt system, as tools e as mensagens que o precederam permanecem inalterados. Consulte Manter o prefixo inalterado. O erro significa que algo anterior na conversa mudou entre as solicitações: um turno editado, reordenado ou removido, um lembrete por turno que foi injetado e depois removido, um prompt system ou array tools reconstruído, ou uma compactação no lado do cliente que manteve os turnos recentes e seu pensamento literalmente. A verificação é aplicada para novas contas criadas a partir de 31 de agosto de 2026 e para qualquer solicitação que defina thinking.block_binding.prefix_mismatch_behavior. A compactação e a edição de contexto no lado do servidor nunca a acionam.

Para corrigir, mantenha o histórico apenas com acréscimos: reenvie os turnos anteriores exatamente como foram enviados e recebidos, adicione instruções com uma mensagem do sistema no meio da conversa em vez de editar system ou tools, e deixe que a edição de contexto ou a compactação no lado do servidor faça qualquer redução. Repetir o mesmo corpo de solicitação não elimina o erro. Para continuar esta solicitação sem o raciocínio invalidado, envie o cabeçalho beta thinking-binding-controls-2026-08-01 e defina thinking.block_binding.prefix_mismatch_behavior como "drop_block". Alternativamente, remova todos os blocos thinking e redacted_thinking do histórico (no mínimo o bloco indicado e todos os posteriores a ele, nesse turno e em todos os turnos seguintes), mantenha os outros blocos de cada turno no lugar e tente novamente uma vez. No Claude Sonnet 5.5 e no Claude Haiku 5.5, block_binding funciona apenas com thinking: {"type": "adaptive"}. Com between_tools no Claude Sonnet 5.5, ou thinking: {"type": "disabled"} no Claude Haiku 5.5, mantenha o histórico apenas com acréscimos, ou remova os blocos de pensamento a partir do turno editado.

Um bloco de um modelo que o modelo de destino não consegue ler nunca produz esse erro: a API o descarta e, com o cabeçalho beta, o relata em input_transformations.

O campo thinking está vazio na resposta

A resposta contém blocos thinking, mas o campo thinking deles é uma string vazia e somente o campo signature está preenchido.

Isso acontece porque display tem como padrão "omitted" nos modelos mais recentes, o que retorna os blocos de pensamento sem o texto.

Defina display: "summarized" na sua configuração de pensamento para receber o texto resumido do pensamento. Consulte Controlando a exibição do pensamento para ver os padrões por modelo. Se você quiser apenas as breves linhas de status que alguns modelos escrevem entre chamadas de ferramentas, e não o raciocínio, defina display: "updates" (beta) em vez disso. Consulte Atualizações de progresso entre chamadas de ferramentas.

Um bloco cujo campo thinking está vazio ainda está completo: a signature contém o raciocínio. Envie-o de volta com o turno como qualquer outro. Consulte Enviar os turnos do assistente de volta exatamente como retornados.

Nenhum bloco de pensamento aparece em alguns turnos

Algumas respostas não contêm nenhum bloco thinking, mesmo com o pensamento configurado.

Isso é normal no modo adaptativo: Claude pula o pensamento em solicitações que considera simples o suficiente para responder diretamente.

Se você quiser que o pensamento ocorra com mais frequência ou mais profundidade, aumente o effort ou oriente por meio do prompt; consulte Orientando a frequência com que Claude pensa.

Um tool_choice forçado ({"type": "any"} ou uma ferramenta nomeada) também não retorna nenhum bloco thinking: a resposta começa com a chamada de ferramenta. Para permitir que o modelo pense antes de chamar uma ferramenta, use tool_choice: {"type": "auto"} e indique no prompt quando usar a ferramenta.

Chamadas de ferramentas ou tags XML aparecem na saída de texto

Ocasionalmente, uma resposta escreve uma chamada de ferramenta em seu texto em vez de emitir um bloco tool_use, ou inclui <thinking> ou outras tags XML internas em seu texto visível. Uma chamada de ferramenta vazada nunca é executada e, em loops agênticos, o texto vazado permanece no histórico da conversa, de modo que os turnos posteriores também são afetados.

Isso acontece no Claude Opus 5 quando o pensamento está desativado, mais comumente em cargas de trabalho com uso intenso de ferramentas, como pesquisa. Regras no prompt do sistema que instruem o modelo a não pensar ou a não raciocinar aumentam o vazamento de tags.

Reative o pensamento (o padrão) e use níveis de effort mais baixos para controlar o custo de tokens. Se sua integração precisar manter o pensamento desativado, aplique as mitigações de prompt em Executando com o pensamento desativado.

A resposta para com stop_reason: "max_tokens"

A resposta termina com stop_reason: "max_tokens", frequentemente com um bloco de texto truncado ou ausente.

Isso acontece porque os tokens de pensamento contam para max_tokens, de modo que uma longa etapa de pensamento pode consumir o orçamento antes que a resposta em texto seja concluída.

Aumente max_tokens para deixar espaço tanto para o pensamento quanto para o texto, ou reduza o effort para que Claude gaste menos com o pensamento; consulte Controle de custos e Pensamento e a janela de contexto.

Os acertos de cache caem após alterar as configurações de pensamento

cache_read_input_tokens cai para zero em solicitações que antes acertavam o cache.

Isso acontece porque a configuração de pensamento e o nível de effort (ou seu padrão) fazem parte do prefixo do prompt em cache, portanto alterar qualquer um deles inicia um novo prefixo: trocar o modo de pensamento, alterar o valor de effort e alterar budget_tokens invalidam os pontos de interrupção de cache das mensagens e também podem invalidar os pontos de interrupção de ferramentas e do prompt do sistema, dependendo de onde o modelo renderiza a configuração.

Mantenha a configuração de pensamento e o nível de effort constantes entre solicitações que compartilham uma conversa; definir explicitamente um parâmetro com seu valor padrão equivale a omiti-lo e não causa invalidação. Consulte Pensamento e "prompt caching" (cache de prompt).

Definir o effort não altera o pensamento

Você altera o effort, mas a frequência ou a profundidade do pensamento permanece a mesma.

Isso acontece porque o effort é o principal controle do pensamento somente no modo adaptativo. Em modelos que suportam apenas pensamento estendido, a profundidade do pensamento é definida por budget_tokens.

Ajuste budget_tokens nesses modelos ou verifique em qual modo seu modelo é executado; consulte Pensamento e effort. No Claude Opus 4.5, o único modelo somente com pensamento estendido que suporta effort, o effort atua em conjunto com o orçamento; consulte Regras e ajuste do orçamento.

Próximos passos