Solução de problemas de pensamento

Esta página cobre as falhas mais comuns ao configurar o pensamento ou ao fazer o round-trip de blocos de pensamento (enviar de volta os blocos de pensamento retornados em requisições posteriores). A primeira seção mapeia cada modelo para as configurações de pensamento que ele suporta e as que ele rejeita; as seções seguintes partem cada uma de um sintoma que você observa, para que você possa associar uma mensagem de erro ou resposta inesperada diretamente à sua causa e correção. Para saber como o pensamento funciona, consulte a visão geral de Pensamento.



Configurações que cada modelo rejeita

A maioria dos erros de configuração de pensamento é uma incompatibilidade entre o valor de thinking.type na requisição e o que o modelo suporta. Nos modelos atuais, o pensamento é executado como thinking: {type: "adaptive"}, e nos mais recentes ele está ativado por padrão. Alguns modelos anteriores usam, em vez disso, o 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 thinking, o pensamento estendido é o único modo de thinking disponível. Claude Mythos Preview suporta ambos os modos. Onde ambos os modos estão disponíveis, use adaptive thinking 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.

¹ enabled e budget_tokens ainda funcionam nesses modelos, mas estão descontinuados; use o pensamento adaptativo em vez disso.
² Claude Opus 5 aceita "disabled" com effort high ou inferior; combiná-lo com effort xhigh ou max retorna um erro 400. Essa restrição se aplica ao Claude Opus 5 e modelos posteriores e é aplicada em cada requisição.

Modelos marcados como Sempre ativado não podem desativar o pensamento. Modelos marcados como Ativado têm o pensamento como padrão, mas aceitam thinking: {type: "disabled"}.

Modelos Claude 4 anteriores (Claude Sonnet 4 e Claude Opus 4) suportam apenas pensamento estendido; consulte descontinuações de modelos para sua disponibilidade. Claude Fable 5 e Claude Mythos 5 não estão disponíveis sob retenção zero de dados.



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

A requisiçã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 que você solicitou removeu o pensamento estendido (consulte Configurações que cada modelo rejeita).

Mude a requisiçã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 diz que "thinking.type.disabled" não é suportado

A requisição falha com um erro 400 cuja 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 em modelos onde o pensamento está sempre ativado: Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview rejeitam "disabled". No Claude Fable 5 e no Claude Mythos 5, a sugestão de "thinking.type.enabled" no texto do erro também não se aplica: esses modelos também a rejeitam.

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

Um erro 400 em "disabled" também pode ocorrer no Claude Opus 5, que aceita thinking: {type: "disabled"} apenas com effort high ou inferior: combiná-lo com effort xhigh ou max é rejeitado. Reduza o nível de effort ou deixe o pensamento ativado.



Um erro 400 diz que o pensamento adaptativo não é suportado

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

adaptive thinking is not supported on this model

Isso acontece porque o modelo suporta apenas o pensamento estendido (consulte Configurações que cada modelo rejeita).

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



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

Uma requisiçã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 de múltiplos turnos e de uso de ferramentas, você envia mensagens anteriores do assistente, incluindo seus blocos thinking e redacted_thinking, de volta para a API, e a API verifica se eles 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 blocos de conteúdo por tipo e descarta blocos redacted_thinking, ou reconstrói a mensagem do assistente em vez de ecoá-la.

Ecoe o turno do assistente de volta literalmente, incluindo os blocos de pensamento. Consulte Preservando blocos de pensamento para as regras, e o round-trip detalhado em Pensamento em fluxos de trabalho de ferramentas e múltiplos turnos para o código correto em cada SDK.



O campo thinking está vazio na resposta

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

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

Defina display: "summarized" na sua configuração de pensamento para receber o texto de pensamento resumido; consulte Controlando a exibição do pensamento para os padrões por modelo.



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 requisições que ele julga simples o suficiente para responder diretamente.

Se você quiser pensamento com mais frequência ou mais profundidade, aumente o effort ou direcione com prompting; consulte Direcionando a frequência com que Claude pensa.



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

Uma resposta ocasionalmente 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 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 busca. Regras no prompt do sistema instruindo o modelo a não pensar ou não raciocinar aumentam o vazamento de tags.

Reative o pensamento (o padrão) e use níveis mais baixos de effort para controlar o custo de tokens em vez disso. Se sua integração precisar manter o pensamento desativado, aplique as mitigações de prompting 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, então uma passagem longa de pensamento pode consumir o orçamento antes que a resposta de 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 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 requisições que anteriormente 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 de prompt em cache, então alterar qualquer um deles inicia um novo prefixo: trocar os modos de pensamento, alterar o valor de effort e alterar budget_tokens invalidam todos os pontos de interrupção de cache de mensagens, e também podem invalidar 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 requisições que compartilham uma conversa; definir um parâmetro explicitamente com seu valor padrão é equivalente a omiti-lo e não invalida. Consulte Pensamento e cache de prompt.



Definir effort não altera o pensamento

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

Isso acontece porque o effort é a alavanca principal do pensamento apenas 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 exclusivamente de pensamento estendido que suporta effort, o effort se compõe com o orçamento; consulte Regras e ajuste de orçamento.



Próximos passos