Risoluzione dei problemi del ragionamento

Questa pagina tratta gli errori più comuni che si verificano quando si configura il "thinking" (ragionamento) o si effettua il round-trip dei blocchi di ragionamento (ovvero si rimandano indietro, nelle richieste successive, i blocchi di ragionamento restituiti). La prima sezione associa ciascun modello alle configurazioni di ragionamento 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 ragionamento, consulta la panoramica Ragionamento.

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

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

L'"extended thinking" (ragionamento 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 ragionamento 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 (ragionamento adattivo).

La tabella elenca ciò che ogni modello supporta, il suo valore predefinito e quali valori di thinking.type rifiuta con un errore 400; qualsiasi valore non elencato come rifiutato è accettato. Solo Claude Sonnet 5.5 accetta "between_tools", e accetta questo valore al posto di "disabled".

¹ enabled e budget_tokens funzionano ancora su questi modelli ma sono deprecati; usa invece il ragionamento adattivo.
² Claude Opus 5 e Claude Haiku 5.5 accettano "disabled" con effort high o inferiore; combinarlo con effort xhigh o max restituisce un errore 400. Su Claude Opus 5, questa restrizione viene applicata a ogni richiesta. Su Claude Haiku 5.5, anche un effort per messaggio diverso dal livello in vigore restituisce un errore 400.
³ Claude Sonnet 5.5 accetta "between_tools" con effort high o inferiore. Combinarlo con effort xhigh o max restituisce un errore 400, così come un effort per messaggio diverso dal livello in vigore.

I modelli contrassegnati come Sempre attivo non possono disattivare il ragionamento. I modelli contrassegnati come Attivo ragionano per impostazione predefinita. Claude Opus 5, Claude Sonnet 5 e Claude Haiku 5.5 accettano thinking: {type: "disabled"}. Su Claude Sonnet 5.5, invia thinking: {type: "between_tools"} per disattivare il ragionamento iniziale.

I modelli Claude 4 precedenti (Claude Opus 4.1, Claude Sonnet 4 e Claude Opus 4) supportano solo il ragionamento 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 la conservazione zero dei dati 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 ragionamento esteso (vedi la tabella di configurazione per modello).

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

Un errore 400 dopo l'invio di thinking: {type: "disabled"}

La richiesta non riesce con un errore 400. Su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5 e Claude Mythos 5, il messaggio recita:

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

Su Claude Mythos Preview, l'unico di questi modelli che accetta il ragionamento esteso, il 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 perché il ragionamento è sempre attivo per tutti questi modelli (consulta la tabella di configurazione per modello).

Ometti il parametro thinking; questi modelli ragionano senza alcuna configurazione. Se il tuo obiettivo era escludere il testo del ragionamento dalle risposte, usa display: "omitted" invece di disattivare il ragionamento; consulta Controllare la visualizzazione del ragionamento.

Un errore 400 su "disabled" può verificarsi anche su Claude Opus 5 e Claude Haiku 5.5, che accettano thinking: {type: "disabled"} solo con effort high o inferiore: combinarlo con effort xhigh o max viene rifiutato. Abbassa il livello di effort, oppure imposta thinking su {"type": "adaptive"}.

Su Claude Sonnet 5.5, thinking: {type: "disabled"} restituisce un errore 400 a qualsiasi livello di effort. Il messaggio recita:

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.

Per disattivare il ragionamento iniziale su Claude Sonnet 5.5, invia invece thinking: {type: "between_tools"}, con effort high o inferiore.

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

La richiesta non riesce con un errore 400 il cui messaggio recita:

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

Questo accade perché solo Claude Sonnet 5.5 accetta thinking: {type: "between_tools"} (consulta la tabella di configurazione per modello).

Invia between_tools solo a Claude Sonnet 5.5. Sugli altri modelli, ometti thinking oppure usa un valore di thinking.type che la tabella non elenca come rifiutato.

Un errore 400 indica che un livello di effort non è supportato quando il ragionamento è disattivato

Su Claude Sonnet 5.5, una richiesta con thinking: {type: "between_tools"} ed effort xhigh o max non riesce con un errore 400 il cui messaggio recita:

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

Questo accade perché Claude Sonnet 5.5 accetta between_tools solo con effort high o inferiore. Il messaggio indica che il ragionamento è disattivato perché between_tools non prevede ragionamento iniziale, anche se la richiesta non ha inviato "disabled". Il messaggio riporta il livello inviato dalla richiesta.

Abbassa l'effort a high o inferiore. Per usare xhigh o max, usa il ragionamento adattivo: ometti il campo thinking oppure invia thinking: {"type": "adaptive"}. È questo che il messaggio intende con "enable thinking". Claude Sonnet 5.5 rifiuta "enabled" con un errore 400.

Claude Haiku 5.5 restituisce lo stesso messaggio quando una richiesta invia thinking: {type: "disabled"} con effort xhigh o max. Accetta "disabled" solo con high o inferiore. Abbassa l'effort, oppure imposta thinking su {"type": "adaptive"}.

Un errore 400 indica che l'effort non può cambiare quando il ragionamento è disattivato

Su Claude Sonnet 5.5, una richiesta con thinking: {type: "between_tools"} il cui effort per messaggio cambia il livello non riesce con un errore 400 il cui messaggio recita:

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.

Il messaggio indica che il ragionamento è disattivato perché between_tools non prevede ragionamento iniziale. Con between_tools, l'effort non può cambiare a metà conversazione: un output_config.effort per messaggio diverso dal livello in vigore restituisce un errore 400. messages.N è la posizione del messaggio che ha impostato il nuovo livello.

Rimuovi quell'effort per messaggio, oppure impostalo sul livello in vigore. Per variare l'effort a ogni turno, usa il ragionamento adattivo: ometti il campo thinking oppure invia thinking: {"type": "adaptive"}. È questo che il messaggio intende con "enable thinking".

Claude Haiku 5.5 restituisce lo stesso messaggio quando una richiesta con thinking: {type: "disabled"} imposta un effort per messaggio diverso dal livello in vigore. Rimuovi quell'effort per messaggio, oppure imposta thinking su {"type": "adaptive"} per variare l'effort a ogni turno.

Un errore 400 indica che il ragionamento 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 ragionamento esteso (vedi la tabella di configurazione per modello).

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

Un errore 400 indica che i blocchi di ragionamento 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 ragionamento inclusi. Consulta Preservare i blocchi di ragionamento per le regole, e il round-trip completo in Il ragionamento 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 ragionamento non è valida

Una richiesta a Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 o Claude Haiku 5.5 che riproduce blocchi di ragionamento precedenti non riesce 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 di solito termina con una frase che indica cosa è cambiato: il prompt system, l'elenco tools, il primo messaggio o blocco che differisce, contenuto mancante o nuovo, oppure un blocco di ragionamento precedente mancante o fuori ordine. Quella frase è destinata alle persone e ai log. La sua formulazione può cambiare, quindi non basarti su di essa nel codice.

Se il messaggio si interrompe dopo Invalid `signature` in `thinking` block, è la firma stessa a non essere stata verificata: è stata troncata, alterata o rinviata vuota, e prefix_mismatch_behavior non si applica. Un testo di ragionamento modificato restituisce un errore diverso. Consulta Un errore 400 indica che i blocchi di ragionamento non possono essere modificati.

Su Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5, l'API accetta un blocco di ragionamento riprodotto solo finché il prompt system, i tools e i messaggi che lo precedono restano invariati. Consulta Mantenere invariato il prefisso. L'errore significa che qualcosa di precedente nella conversazione è cambiato tra una richiesta e l'altra: un turno modificato, riordinato o rimosso, un promemoria per turno 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 ragionamento. Il controllo viene applicato per i nuovi account creati a partire dal 31 agosto 2026 e per qualsiasi richiesta che imposti thinking.block_binding.prefix_mismatch_behavior. La compattazione e la modifica del contesto lato server non lo attivano mai.

Per risolverlo, mantieni la cronologia in sola aggiunta: rinvia i turni precedenti esattamente come sono stati 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 riduzioni. 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 successivi), lascia al loro posto gli altri blocchi di ciascun turno e riprova una volta. Su Claude Sonnet 5.5 e Claude Haiku 5.5, block_binding funziona solo con thinking: {"type": "adaptive"}. Con between_tools su Claude Sonnet 5.5, o thinking: {"type": "disabled"} su Claude Haiku 5.5, mantieni la cronologia in sola aggiunta, oppure rimuovi i blocchi di ragionamento a partire dal turno modificato.

Un blocco proveniente da un modello che il modello di destinazione non è in grado di 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 ragionamento senza il loro testo.

Imposta display: "summarized" nella configurazione del ragionamento per ricevere il testo del ragionamento riassunto. Consulta Controllare la visualizzazione del ragionamento 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.

Un blocco il cui campo thinking è vuoto è comunque completo: la signature contiene il ragionamento. Rimandalo con il turno come qualsiasi altro blocco. Consulta Rimanda i turni dell'assistente esattamente come restituiti.

In alcuni turni non compare alcun blocco di ragionamento

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

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

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

Anche un tool_choice forzato ({"type": "any"} o uno strumento specifico) non restituisce alcun blocco thinking: la risposta inizia con la chiamata allo strumento. Per consentire al modello di ragionare prima di chiamare uno strumento, usa tool_choice: {"type": "auto"} e indica nel prompt quando usare lo strumento.

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 ragionamento è 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 ragionamento (l'impostazione predefinita) e usa invece livelli di effort più bassi per controllare il costo in token. Se la tua integrazione deve mantenere il ragionamento disattivato, applica le mitigazioni di prompting descritte in Esecuzione con il ragionamento disabilitato.

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 ragionamento vengono conteggiati in max_tokens, quindi un lungo passaggio di ragionamento può consumare il budget prima che la risposta testuale sia completa.

Aumenta max_tokens per lasciare spazio sia al ragionamento sia al testo, oppure abbassa effort in modo che Claude spenda meno nel ragionamento; consulta Controllo dei costi e Ragionamento e finestra di contesto.

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

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

Questo accade perché la configurazione del ragionamento 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 ragionamento, 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 ragionamento 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 Ragionamento e cache dei prompt.

Impostare effort non modifica il ragionamento

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

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

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

Passaggi successivi