Solução de problemas de pensamento

Esta página aborda as falhas mais comuns ao configurar o pensamento ou ao fazer o round-trip de blocos de pensamento (enviar blocos de pensamento retornados de volta em requisições posteriores). A primeira seção mapeia cada modelo às suas configurações de pensamento suportadas e às que ele rejeita; as seções seguintes começam cada uma a partir 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 entender 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 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" no nível de 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 Opus 4.1, Claude Sonnet 4 e Claude Opus 4) suportam apenas pensamento estendido; consulte Descontinuações de modelos para verificar 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).

Altere a requisição para thinking: {type: "adaptive"} e direcione a profundidade do pensamento com effort em vez de budget_tokens. Migrando para o pensamento adaptativo orienta você pela conversão.



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 nos quais 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 a rejeitam igualmente.

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 no nível de 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 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 blocos de pensamento não podem ser modificados

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

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

Em conversas multi-turno e de uso de ferramentas, você envia mensagens anteriores do assistente, incluindo seus blocos thinking e redacted_thinking, de volta à 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, geralmente 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 multi-turno 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 seu 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 julga simples o suficiente para responder diretamente.

Se você quiser que o pensamento ocorra 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 intensivo 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 o 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.



Acertos de cache caem após alterar 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: alternar modos de pensamento, alterar o valor de effort e alterar budget_tokens invalidam todos os pontos de interrupção de cache de mensagens, e podem invalidar também 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 requisições que compartilham uma conversa; definir um parâmetro explicitamente com seu valor padrão é equivalente a omiti-lo e não invalida o cache. Consulte Pensamento e cache de prompt.



Definir effort não altera o pensamento

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

Isso acontece porque effort é a alavanca principal de 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 está executando; consulte Pensamento e effort. No Claude Opus 4.5, o único modelo exclusivo de pensamento estendido que suporta effort, o effort se compõe com o orçamento; consulte Regras de orçamento e ajuste.



Próximos passos