Risoluzione dei problemi del pensiero

Questa pagina tratta gli errori più comuni che si verificano quando si configura il "thinking" (pensiero) o si effettua il round-trip dei blocchi di pensiero (ovvero si rimandano indietro, nelle richieste successive, i blocchi di pensiero restituiti). La prima sezione associa ciascun modello alle configurazioni di pensiero supportate e a quelle che rifiuta; le sezioni successive partono ciascuna da un sintomo osservato, così puoi collegare direttamente un messaggio di errore o una risposta inattesa alla sua causa e alla relativa soluzione. Per capire come funziona il pensiero, consulta la panoramica Pensiero.

Supporto del pensiero, valori predefiniti e configurazioni rifiutate per modello

La maggior parte degli errori di configurazione del pensiero deriva da una discrepanza tra il valore thinking.type nella richiesta e ciò che il modello supporta. Sulla maggior parte dei modelli, il pensiero viene eseguito come thinking: {type: "adaptive"}, e molti lo hanno attivo per impostazione predefinita. Alcuni modelli precedenti usano invece l'"extended thinking" (pensiero esteso), una modalità manuale legacy configurata come thinking: {type: "enabled", budget_tokens: N}.

L'"extended thinking" (pensiero esteso) (thinking.type: "enabled" con budget_tokens) è deprecato sui modelli Claude 4.6 (le richieste che lo utilizzano hanno comunque esito positivo). Claude 4.7 e i modelli successivi non lo supportano e rifiutano le richieste che lo utilizzano, restituendo un errore 400. Su Claude 4.5 e sui modelli precedenti che supportano il thinking, il pensiero esteso è l'unica modalità di thinking disponibile. Claude Mythos Preview supporta entrambe le modalità. Dove sono disponibili entrambe le modalità, usa invece l'adaptive thinking (pensiero adattivo).

La tabella elenca ciò che ciascun modello supporta, il suo valore predefinito e quali valori di thinking.type rifiuta con un errore 400; qualsiasi valore non elencato come rifiutato è accettato.

¹ enabled e budget_tokens funzionano ancora su questi modelli ma sono deprecati; usa invece il pensiero adattivo.
² Claude Opus 5 accetta "disabled" con effort high o inferiore; combinarlo con effort xhigh o max restituisce un errore 400. Questa restrizione si applica a Claude Opus 5 e ai modelli successivi e viene applicata a ogni richiesta.

I modelli contrassegnati come Sempre attivo non possono disattivare il pensiero. I modelli contrassegnati come Attivo hanno il pensiero attivo per impostazione predefinita ma accettano thinking: {type: "disabled"}.

I modelli Claude 4 precedenti (Claude Opus 4.1, Claude Sonnet 4 e Claude Opus 4) supportano solo il pensiero esteso. Consulta Deprecazioni dei modelli per la loro disponibilità. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 non sono disponibili con zero data retention salvo espressa autorizzazione di Anthropic.

Un errore 400 indica che "thinking.type.enabled" non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

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

Questo accade perché il modello richiesto ha rimosso il pensiero esteso (vedi la tabella di configurazione per modello).

Passa la richiesta a thinking: {type: "adaptive"} e regola la profondità del pensiero con effort invece di budget_tokens. Migrazione al pensiero adattivo illustra la conversione passo per passo.

Un errore 400 indica che "thinking.type.disabled" non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

"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.

Questo accade sui modelli in cui il pensiero è sempre attivo: Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview rifiutano "disabled". Tutti questi, tranne Claude Mythos Preview, rifiutano anche il "thinking.type.enabled" suggerito dal testo dell'errore.

Ometti il parametro thinking; questi modelli pensano senza alcuna configurazione. Se il tuo obiettivo era escludere il testo del pensiero dalle risposte, usa display: "omitted" invece di disattivare il pensiero; consulta Controllo della visualizzazione del pensiero.

Un errore 400 su "disabled" può verificarsi anche su Claude Opus 5, che accetta thinking: {type: "disabled"} solo con effort high o inferiore: combinarlo con effort xhigh o max viene rifiutato. Abbassa il livello di effort oppure lascia il pensiero attivo.

Un errore 400 indica che il pensiero adattivo non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

adaptive thinking is not supported on this model

Questo accade perché il modello supporta solo il pensiero esteso (vedi la tabella di configurazione per modello).

Usa invece thinking: {type: "enabled", budget_tokens: N}; consulta Pensiero esteso per la configurazione.

Un errore 400 indica che i blocchi di pensiero non possono essere modificati

Una richiesta che restituisce risultati di strumenti fallisce con un errore 400 invalid_request_error il cui messaggio contiene:

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

Nelle conversazioni multi-turno e con "tool use" (uso degli strumenti) rimandi all'API i messaggi precedenti dell'assistente, inclusi i loro blocchi thinking e redacted_thinking, e l'API verifica che arrivino non modificati. Questo errore si verifica quando il messaggio dell'assistente che rimandi differisce da quello restituito dall'API, il più delle volte perché il tuo codice filtra i blocchi di contenuto per tipo e scarta i blocchi redacted_thinking, oppure ricostruisce il messaggio dell'assistente invece di riproporlo così com'è.

Riproponi il turno dell'assistente alla lettera, blocchi di pensiero inclusi. Consulta Preservare i blocchi di pensiero per le regole, e il round-trip completo in Il pensiero nei flussi di lavoro con strumenti e multi-turno per il codice corretto in ogni SDK.

Un errore 400 indica che la firma di un blocco di pensiero non è valida

Una richiesta a Claude Fable 5.1 che ripropone blocchi di pensiero precedenti fallisce con un errore 400 invalid_request_error il cui messaggio recita:

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 la richiesta non ha inviato l'header beta thinking-binding-controls-2026-08-01, il messaggio aggiunge That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header. Il messaggio può anche terminare con una frase che indica il primo messaggio che è cambiato. Se il messaggio non contiene alcuna clausola di motivazione, il contenuto del blocco è stato modificato. Consulta Un errore 400 indica che i blocchi di pensiero non possono essere modificati.

Su Claude Fable 5.1, l'API accetta un blocco di pensiero riproposto solo finché il prompt system, i tools e i messaggi che lo precedevano restano invariati. L'errore significa che qualcosa di precedente nella conversazione è cambiato tra le richieste: un turno modificato, riordinato o rimosso, un promemoria per turno che è stato inserito e poi rimosso, un prompt system o un array tools ricostruito, oppure una compattazione lato client che ha mantenuto alla lettera i turni recenti e il loro pensiero. Il controllo viene applicato ai nuovi account creati a partire dal 31 agosto 2026 e a qualsiasi richiesta che imposti thinking.block_binding.prefix_mismatch_behavior. La compattazione lato server e la modifica del contesto non lo attivano mai.

Per risolverlo, mantieni la cronologia in sola aggiunta: rimanda i turni precedenti esattamente come inviati e ricevuti, aggiungi istruzioni con un messaggio di sistema a metà conversazione invece di modificare system o tools, e lascia che la modifica del contesto o la compattazione lato server si occupino di eventuali tagli. Riprovare con lo stesso corpo della richiesta non elimina l'errore. Per proseguire questa richiesta senza il ragionamento invalidato, invia l'header beta thinking-binding-controls-2026-08-01 e imposta thinking.block_binding.prefix_mismatch_behavior su "drop_block". In alternativa, rimuovi ogni blocco thinking e redacted_thinking dalla cronologia (come minimo il blocco indicato e tutti quelli successivi, in quel turno e in tutti i turni seguenti), lascia al loro posto gli altri blocchi di ciascun turno e riprova una volta.

Un blocco proveniente da un modello che il modello di destinazione non può leggere non produce mai questo errore: l'API lo scarta e, con l'header beta, lo segnala in input_transformations.

Il campo thinking è vuoto nella risposta

La risposta contiene blocchi thinking, ma il loro campo thinking è una stringa vuota e solo il campo signature è popolato.

Questo accade perché display ha come valore predefinito "omitted" sui modelli più recenti, il che restituisce i blocchi di pensiero senza il loro testo.

Imposta display: "summarized" nella configurazione del pensiero per ricevere il testo del pensiero riassunto. Consulta Controllo della visualizzazione del pensiero per i valori predefiniti per modello. Se vuoi solo le brevi righe di stato che alcuni modelli scrivono tra le chiamate agli strumenti, e non il ragionamento, imposta invece display: "updates" (beta). Consulta Aggiornamenti di avanzamento tra le chiamate agli strumenti.

In alcuni turni non compare alcun blocco di pensiero

Alcune risposte non contengono alcun blocco thinking, anche se il pensiero è configurato.

Questo è normale in modalità adattiva: Claude salta il pensiero nelle richieste che giudica abbastanza semplici da poter rispondere direttamente.

Se vuoi che il pensiero avvenga più spesso o più in profondità, aumenta effort o guida il comportamento con il prompting; consulta Regolare la frequenza con cui Claude pensa.

Chiamate agli strumenti o tag XML compaiono nell'output di testo

Una risposta occasionalmente scrive una chiamata a uno strumento nel proprio testo invece di emettere un blocco tool_use, oppure include <thinking> o altri tag XML interni nel testo visibile. Una chiamata a strumento trapelata non viene mai eseguita e, nei cicli agentici, il testo trapelato rimane nella cronologia della conversazione, quindi anche i turni successivi ne risentono.

Questo accade su Claude Opus 5 quando il pensiero è disattivato, più comunemente nei carichi di lavoro con uso intensivo di strumenti come la ricerca. Le regole nel "system prompt" (prompt di sistema) che istruiscono il modello a non pensare o a non ragionare aumentano la fuoriuscita dei tag.

Riattiva il pensiero (l'impostazione predefinita) e usa invece livelli di effort più bassi per controllare il costo in token. Se la tua integrazione deve mantenere il pensiero disattivato, applica le mitigazioni di prompting descritte in Esecuzione con il pensiero disattivato.

La risposta si interrompe con stop_reason: "max_tokens"

La risposta termina con stop_reason: "max_tokens", spesso con un blocco di testo troncato o mancante.

Questo accade perché i token di pensiero vengono conteggiati in max_tokens, quindi un lungo passaggio di pensiero può consumare il budget prima che la risposta testuale sia completa.

Aumenta max_tokens per lasciare spazio sia al pensiero sia al testo, oppure abbassa effort in modo che Claude spenda meno nel pensiero; consulta Controllo dei costi e Il pensiero e la "context window" (finestra di contesto).

I riscontri nella cache calano dopo aver modificato le impostazioni del pensiero

cache_read_input_tokens scende a zero su richieste che in precedenza trovavano riscontro nella cache.

Questo accade perché la configurazione del pensiero e il livello di effort (o il suo valore predefinito) fanno parte del prefisso del prompt memorizzato nella cache, quindi modificare uno qualsiasi di essi avvia un nuovo prefisso: cambiare modalità di pensiero, cambiare il valore di effort e cambiare budget_tokens invalidano tutti i breakpoint della cache dei messaggi, e possono invalidare anche i breakpoint degli strumenti e del prompt di sistema, a seconda di dove il modello rende la configurazione.

Mantieni costanti la configurazione del pensiero e il livello di effort tra le richieste che condividono una conversazione; impostare esplicitamente un parametro al suo valore predefinito equivale a ometterlo e non invalida la cache. Consulta Il pensiero e la "prompt caching" (cache dei prompt).

Impostare effort non modifica il pensiero

Modifichi effort ma la frequenza o la profondità del pensiero restano invariate.

Questo accade perché effort è la leva principale del pensiero solo in modalità adattiva. Sui modelli che supportano solo il pensiero esteso, la profondità del pensiero è invece determinata da budget_tokens.

Regola budget_tokens su quei modelli, oppure verifica in quale modalità viene eseguito il tuo modello; consulta Pensiero ed effort. Su Claude Opus 4.5, l'unico modello con solo pensiero esteso che supporta effort, effort si combina con il budget; consulta Regole e ottimizzazione del budget.

Passaggi successivi