Vai al contenuto principale
Questa pagina elenca gli errori di runtime che Claude Code visualizza e come recuperare da ciascuno, oltre a cosa controllare quando le risposte sembrano non corrette senza un errore. Per gli errori di installazione come command not found o errori TLS durante la configurazione, vedi Troubleshooting installation and login. Questi errori e i comandi di recupero si applicano su CLI, l’app Desktop e Claude Code sul web, poiché tutti e tre avvolgono lo stesso Claude Code CLI. Per problemi specifici della superficie, vedi la sezione troubleshooting nella pagina di quella superficie.
Claude Code chiama l’API Claude per le risposte del modello, quindi la maggior parte degli errori di runtime si mappano a un codice di errore API sottostante. Questa pagina copre cosa significa ogni errore all’interno di Claude Code e come recuperare. Per le definizioni del codice di stato HTTP grezzo, vedi il riferimento degli errori della piattaforma Claude.

​
Trova il tuo errore

Abbina il messaggio che vedi nel tuo terminale a una sezione sottostante.
MessaggioSezione
API Error: 500 Internal server errorErrori del server
API Error: Repeated 529 Overloaded errorsErrori del server
Request timed outErrori del server, o Rete se il messaggio menziona la tua connessione internet
<model> is temporarily unavailable, so auto mode cannot determine the safety of...Errori del server
Auto mode could not evaluate this action and is blocking it for safetyErrori del server
Auto mode classifier transcript exceeded context windowErrori del server
You've hit your session limit / You've hit your weekly limitLimiti di utilizzo
Server is temporarily limiting requestsLimiti di utilizzo
Request rejected (429)Limiti di utilizzo
Credit balance is too lowLimiti di utilizzo
Not logged in · Please run /loginAutenticazione
Invalid API keyAutenticazione
This organization has been disabledAutenticazione
Your organization has disabled Claude subscription accessAutenticazione
Routines are disabled by your organization's policyAutenticazione
OAuth token revoked / OAuth token has expiredAutenticazione
does not meet scope requirement user:profileAutenticazione
Unable to connect to APIRete
SSL certificate verification failedRete
403 con x-deny-reason: host_not_allowed in una sessione cloud o routineRete
Prompt is too longErrori di richiesta
Error during compaction: Conversation too longErrori di richiesta
Request too largeErrori di richiesta
Image was too largeErrori di richiesta
Unable to resize imageErrori di richiesta
PDF too large / PDF is password protectedErrori di richiesta
Extra inputs are not permittedErrori di richiesta
There's an issue with the selected modelErrori di richiesta
Claude Opus is not available with the Claude Pro planErrori di richiesta
thinking.type.enabled is not supported for this modelErrori di richiesta
max_tokens must be greater than thinking.budget_tokensErrori di richiesta
API Error: 400 due to tool use concurrency issuesErrori di richiesta
Claude Code is unable to respond to this request, which appears to violate our Usage PolicyErrori di richiesta
Le risposte sembrano di qualità inferiore al solitoQualità della risposta

​
Tentativi automatici

Claude Code ritenta i guasti transitori prima di mostrarti un errore. Gli errori del server, le risposte sovraccariche, i timeout delle richieste, i throttle 429 temporanei e le connessioni interrotte vengono tutti ritentati fino a 10 volte con backoff esponenziale. Durante il tentativo, lo spinner mostra un countdown Retrying in Ns · attempt x/y. Quando vedi uno degli errori in questa pagina, quei tentativi sono già stati esauriti. Puoi regolare il comportamento con due variabili di ambiente:
VariabilePredefinitoEffetto
CLAUDE_CODE_MAX_RETRIES10Numero di tentativi di ripetizione. Abbassalo per far emergere i guasti più velocemente negli script; aumentalo per attendere attraverso incidenti più lunghi.
API_TIMEOUT_MS600000Timeout per richiesta in millisecondi. Aumentalo per reti lente o proxy.

​
Errori del server

Questi errori provengono dal provider di inferenza piuttosto che dal tuo account o dalla tua richiesta. Sull’API Anthropic significa infrastruttura Anthropic. Su Bedrock, Vertex AI, Foundry o un gateway personalizzato significa l’infrastruttura di quel provider.

​
API Error: 500 Internal server error

Claude Code mostra il codice di stato e il messaggio di errore dell’API per qualsiasi risposta 5xx. L’esempio sottostante mostra una risposta 500 sull’API Anthropic: 
API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.
La frase finale indica dove controllare l’integrità del servizio e varia in base al provider. Le configurazioni Bedrock, Vertex AI e Foundry indicano lo stato del servizio di quel provider. Un ANTHROPIC_BASE_URL personalizzato indica l’host del gateway. Questo indica un guasto inaspettato all’interno dell’API. Non è causato dal tuo prompt, dalle impostazioni o dal tuo account. Cosa fare:
  • Controlla status.claude.com o la pagina di stato del provider indicata nel messaggio per gli incidenti attivi
  • Attendi un minuto, quindi invia di nuovo il tuo messaggio. Il tuo messaggio originale è ancora nella conversazione, quindi per un prompt lungo puoi digitare try again invece di incollare l’intera cosa.
  • Se l’errore persiste senza un incidente pubblicato, esegui /feedback in modo che Anthropic possa indagare con i dettagli della tua richiesta. Vedi Segnala un errore se /feedback non è disponibile nel tuo ambiente.

​
API Error: Repeated 529 Overloaded errors

L’API è temporaneamente a capacità su tutti gli utenti. Claude Code ha già ritentato più volte prima di mostrare questo messaggio: 
API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.
La frase finale varia in base al provider nello stesso modo dell’errore 500 sopra. Un 529 non è il tuo limite di utilizzo e non conta rispetto alla tua quota. Cosa fare:
  • Controlla status.claude.com o la pagina di stato del provider indicata nel messaggio per gli avvisi di capacità
  • Riprova tra pochi minuti
  • Esegui /model e passa a un modello diverso per continuare a lavorare, poiché la capacità è tracciata per modello. Claude Code ti chiede di farlo quando un modello è sotto un carico particolarmente elevato, ad esempio Opus is experiencing high load, please use /model to switch to Sonnet.

​
Request timed out

L’API non ha risposto prima della scadenza della connessione. 
Request timed out
Questo può accadere durante periodi di carico elevato o quando viene generata una risposta molto grande. Il timeout della richiesta predefinito è di 10 minuti. Cosa fare:
  • Ritenta la richiesta
  • Per attività di lunga durata, suddividi il lavoro in prompt più piccoli
  • Se una rete lenta o un proxy è la causa, aumenta API_TIMEOUT_MS come descritto in Tentativi automatici
  • Se i timeout sono frequenti e la tua rete è altrimenti sana, vedi Errori di rete e connessione sottostante

​
Auto mode cannot determine the safety of an action

Il modello che auto mode utilizza per classificare le azioni non ha potuto produrre una decisione, quindi auto mode non ha approvato l’azione automaticamente. Il messaggio che vedi dipende dal motivo per cui il classificatore ha fallito. Le letture, le ricerche e le modifiche all’interno della tua directory di lavoro saltano il classificatore, quindi continuano a funzionare in tutti questi casi. Quando il modello classificatore è sovraccarico: 
<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.
Cosa fare:
  • Ritenta dopo pochi secondi; Claude vede lo stesso messaggio e di solito ritenta da solo
  • Se i tentativi continuano a fallire, continua con attività di sola lettura e torna all’azione bloccata in seguito
  • Questo è transitorio e non correlato all’idoneità della modalità auto; non è necessario modificare le impostazioni
Quando il classificatore ha restituito una risposta non analizzabile: 
Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details
Cosa fare:
  • Ritenta l’azione; questo di solito ha successo al tentativo successivo
  • Esegui claude --debug e ripeti l’azione per vedere la risposta del classificatore sottostante nel log di debug
Quando la conversazione è cresciuta più grande della finestra di contesto del classificatore: 
Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)
In una sessione interattiva, auto mode ritorna a un normale prompt di autorizzazione per quell’azione in modo che tu possa approvarla o negarla manualmente. In modalità non interattiva l’esecuzione si interrompe perché la trascrizione cresce solo e il ritentativo non può avere successo. Cosa fare:
  • Approva o nega l’azione nel prompt che appare
  • Esegui /compact per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore

​
Limiti di utilizzo

Questi errori significano che una quota legata al tuo account o al tuo piano è stata raggiunta. Sono distinti dagli errori del server, che interessano tutti.

​
You’ve hit your session limit

I piani di abbonamento includono un’indennità di utilizzo mobile. Quando si esaurisce vedi uno di questi messaggi: 
You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
Claude Code blocca ulteriori richieste fino all’ora di ripristino mostrata nel messaggio. Cosa fare:
  • Attendi l’ora di ripristino mostrata nell’errore
  • Esegui /usage per vedere i limiti del tuo piano e quando si ripristinano
  • Esegui /usage-credits per acquistare utilizzo aggiuntivo su Pro e Max, o per richiederlo al tuo amministratore su Team ed Enterprise. Vedi usage credits for paid plans per come viene fatturato.
  • Per aggiornare il tuo piano per limiti di base più elevati, vedi claude.com/pricing
Per controllare la tua indennità rimanente prima di raggiungere il limite, aggiungi i campi rate_limits a una linea di stato personalizzata, o nell’app Desktop fai clic sull’anello di utilizzo accanto al selettore di modello.

​
Server is temporarily limiting requests

L’API ha applicato un throttle di breve durata non correlato alla tua quota del piano. 
API Error: Server is temporarily limiting requests (not your usage limit)
Questo viene ritentato automaticamente prima di essere mostrato. Cosa fare:

​
Request rejected (429)

Hai raggiunto il limite di velocità configurato per la tua chiave API, il progetto Amazon Bedrock o il progetto Google Vertex AI. 
API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.
La frase finale indica dove controllare l’integrità del servizio e varia in base al provider. Le configurazioni Bedrock, Vertex AI e Foundry indicano lo stato del servizio di quel provider invece della pagina di stato Anthropic. Una configurazione ANTHROPIC_BASE_URL personalizzata indica l’host del gateway. Cosa fare:
  • Esegui /status e conferma che la credenziale attiva è quella che ti aspetti. Un ANTHROPIC_API_KEY casuale nel tuo ambiente può instradare le richieste attraverso una chiave di livello inferiore invece del tuo abbonamento.
  • Controlla la console del tuo provider per i limiti attivi e richiedi un livello più elevato se necessario
  • Per le chiavi API Anthropic, vedi il riferimento dei limiti di velocità per come funzionano i livelli e come impostare i limiti per workspace
  • Riduci la concorrenza: abbassa CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, evita di eseguire molti subagent paralleli, o passa a un modello più piccolo con /model per esecuzioni di script ad alto volume

​
Credit balance is too low

La tua organizzazione Console ha esaurito i crediti prepagati. 
Credit balance is too low
Cosa fare:
  • Aggiungi crediti su platform.claude.com/settings/billing, e considera di abilitare l’auto-reload lì in modo che il saldo si ricarichi prima di raggiungere lo zero
  • Passa all’autenticazione tramite abbonamento con /login se hai un piano Pro, Max, Team o Enterprise
  • Imposta i limiti di spesa per workspace nella Console per evitare che un singolo progetto dreni il saldo dell’organizzazione. Vedi Manage costs effectively.

​
Errori di autenticazione

Questi errori significano che Claude Code non può provare chi sei all’API. Esegui /status in qualsiasi momento per vedere quale credenziale è attualmente attiva.

​
Not logged in

Nessuna credenziale valida è disponibile per questa sessione. 
Not logged in · Please run /login
Cosa fare:
  • Esegui /login per autenticarti con il tuo abbonamento Claude o account Console
  • Se ti aspettavi che una variabile di ambiente ti autenticasse, conferma che ANTHROPIC_API_KEY è impostato ed esportato nella shell in cui hai lanciato claude
  • Per CI o automazione in cui l’accesso interattivo non è possibile, configura uno script apiKeyHelper che recupera una chiave all’avvio
  • Vedi Authentication precedence per capire quale credenziale vince quando sono presenti più credenziali
Se ti viene chiesto di accedere ripetutamente, vedi Not logged in or token expired per le correzioni dell’orologio di sistema e del Keychain di macOS.

​
Invalid API key

La variabile di ambiente ANTHROPIC_API_KEY o lo script apiKeyHelper ha restituito una chiave che l’API ha rifiutato. 
Invalid API key · Fix external API key
Cosa fare:
  • Controlla gli errori di battitura e conferma che la chiave non sia stata revocata nella Console
  • Esegui env | grep ANTHROPIC nella stessa shell. Strumenti come direnv, plugin shell dotenv e terminali IDE possono caricare una chiave obsoleta da un file .env nel tuo progetto senza che tu la imposti esplicitamente.
  • Annulla l’impostazione di ANTHROPIC_API_KEY ed esegui /login per utilizzare l’autenticazione tramite abbonamento
  • Se la chiave proviene da uno script apiKeyHelper, esegui lo script direttamente per confermare che stampa una chiave valida su stdout
  • Esegui /status per confermare quale fonte di credenziale Claude Code sta effettivamente utilizzando

​
This organization has been disabled

Una ANTHROPIC_API_KEY obsoleta da un’organizzazione Console disabilitata sta sovrascrivendo il tuo accesso tramite abbonamento. 
Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.
Le variabili di ambiente hanno la precedenza su /login, quindi una chiave esportata nel tuo profilo shell o caricata da un file .env viene utilizzata anche quando hai un abbonamento Pro o Max funzionante. In modalità non interattiva (-p), la chiave viene sempre utilizzata quando presente. Cosa fare:
  • Annulla l’impostazione di ANTHROPIC_API_KEY nella shell corrente e rimuovilo dal tuo profilo shell, quindi riavvia claude
  • Esegui /status in seguito per confermare che la credenziale attiva è il tuo abbonamento
  • Se nessuna variabile di ambiente è impostata e l’errore persiste, l’organizzazione disabilitata è quella legata al tuo /login. Contatta il supporto o accedi con un account diverso.

​
Your organization has disabled Claude subscription access

La tua organizzazione Claude non consente l’accesso a Claude Code con un accesso tramite abbonamento. Eseguire /login di nuovo con lo stesso account restituisce lo stesso errore. 
Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access
Questa è un’impostazione organizzativa lato server, quindi non può essere sovrascritta dalle impostazioni locali, dalle variabili di ambiente o dai flag CLI. L’Agent SDK e la modalità non interattiva -p presentano questo come il codice di errore oauth_org_not_allowed. Cosa fare:
  • Chiedi al tuo amministratore di abilitare l’accesso a Claude Code per la tua organizzazione
  • Autenticati con una chiave API Console invece del tuo abbonamento. Vedi Claude Console authentication per la configurazione.
  • Se sei l’amministratore e non vedi un’opzione per abilitare l’accesso, contatta il supporto Anthropic

​
Routines are disabled by your organization’s policy

L’amministratore del tuo Team o Enterprise ha disattivato le routine a livello organizzativo. L’errore appare quando tenti di creare o eseguire una routine, incluso da /schedule e dall’interfaccia utente Routines su claude.ai/code. 
Routines are disabled by your organization's policy.
Questa è un’impostazione lato server, quindi non può essere sovrascritta dalle impostazioni locali, dalle variabili di ambiente o dai flag CLI. Cosa fare:

​
OAuth token revoked or expired

Il tuo accesso salvato non è più valido. Un token revocato significa che hai effettuato il logout ovunque o un amministratore ha rimosso l’accesso; un token scaduto significa che l’aggiornamento automatico non è riuscito a metà sessione. 
OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_error
Cosa fare:
  • Esegui /login per accedere di nuovo
  • Se l’errore ritorna nella stessa sessione dopo la ri-autenticazione, esegui prima /logout per cancellare completamente il token memorizzato, quindi /login
  • Per prompt ripetuti di accesso tra i lanci, vedi i controlli dell’orologio di sistema e del Keychain di macOS in Troubleshooting
  • Per altri guasti inclusi 403 Forbidden e problemi del browser OAuth, vedi Login and authentication

​
OAuth scope requirement

Il token memorizzato precede un ambito di autorizzazione che una funzione più recente necessita. Lo vedi più spesso da /usage e dall’indicatore di utilizzo della linea di stato: 
OAuth token does not meet scope requirement: user:profile
Cosa fare:
  • Esegui /login per creare un nuovo token con gli ambiti attuali. Non è necessario effettuare il logout prima.

​
Errori di rete e connessione

Questi errori significano che una richiesta di rete da Claude Code non è riuscita a raggiungere la sua destinazione. Di solito provengono dalla tua rete locale, proxy o firewall, o dalla politica di rete dell’ambiente cloud.

​
Unable to connect to API

La connessione TCP all’API non è riuscita o non si è mai completata. 
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settings
Le cause comuni includono nessun accesso a Internet, una VPN che blocca api.anthropic.com, o un proxy aziendale richiesto che non è configurato. Cosa fare:
  • Conferma di poter raggiungere l’host API dalla stessa shell eseguendo curl -I https://api.anthropic.com. Su Windows PowerShell usa curl.exe -I https://api.anthropic.com in modo che l’alias Invoke-WebRequest integrato non venga utilizzato.
  • Se sei dietro un proxy aziendale, imposta HTTPS_PROXY prima di lanciare Claude Code e vedi Network configuration
  • Se instrada attraverso un gateway LLM o relay, imposta ANTHROPIC_BASE_URL al suo indirizzo. Vedi LLM gateway configuration per la configurazione.
  • Assicurati che il tuo firewall consenta gli host elencati in Network access requirements
  • I guasti intermittenti vengono ritentati automaticamente; i guasti persistenti indicano un problema di rete locale
Se curl ha successo ma Claude Code ancora fallisce, la causa è solitamente qualcosa tra il runtime e la rete piuttosto che la rete stessa:
  • Su Linux e WSL, controlla /etc/resolv.conf per un nameserver irraggiungibile. WSL in particolare può ereditare un resolver rotto dall’host.
  • Su macOS, un client VPN che è stato disconnesso o disinstallato può lasciare dietro un’interfaccia tunnel o una regola di routing. Controlla ifconfig per interfacce utun obsolete e rimuovi l’estensione di rete della VPN in Impostazioni di Sistema.
  • Docker Desktop e runtime di container simili possono intercettare il traffico in uscita. Esci da loro e ritenta per escluderlo.

​
SSL certificate errors

Un proxy o un’appliance di sicurezza sulla tua rete sta intercettando il traffico TLS con il suo certificato, e Claude Code non lo considera attendibile. 
Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detected
Cosa fare:
  • Esporta il bundle CA della tua organizzazione e punta Claude Code ad esso con NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
  • Vedi Network configuration per le istruzioni di configurazione complete
  • Non impostare NODE_TLS_REJECT_UNAUTHORIZED=0, che disabilita completamente la convalida del certificato

​
Host not allowed in a cloud session

Una richiesta HTTP in uscita da una sessione cloud o routine è stata bloccata dalla politica di rete dell’ambiente. 
HTTP 403
x-deny-reason: host_not_allowed
Potresti anche vedere un certificato TLS che non corrisponde al certificato reale della destinazione. L’ambiente cloud instrada il traffico in uscita attraverso un proxy che applica la politica di rete, quindi un certificato non corrispondente significa che il proxy ha terminato la connessione, non la destinazione. Questo non è un problema di rete lato client. Le sessioni cloud e le routine vengono eseguite all’interno di un ambiente sandbox la cui rete in uscita è filtrata in base alla lista di autorizzazione dell’ambiente. L’ambiente Default utilizza l’accesso Trusted, che consente la lista di autorizzazione predefinita dei registri di pacchetti, API dei provider cloud, registri di container e domini di sviluppo comuni, ma blocca tutto il resto. Cosa fare:
  • Apri la routine per la modifica, o avvia una sessione cloud. Seleziona l’icona cloud che mostra il nome del tuo ambiente, ad esempio Default, per aprire il selettore. Passa il mouse sopra il tuo ambiente e fai clic sull’icona delle impostazioni.
  • Nella finestra di dialogo Update cloud environment, cambia Network access da Trusted a Custom, quindi aggiungi il dominio bloccato a Allowed domains. Inserisci un dominio per riga. Seleziona Also include default list of common package managers per mantenere la lista di autorizzazione predefinita insieme ai tuoi domini personalizzati. Seleziona Full invece se desideri un accesso senza restrizioni.
  • Fai clic su Save changes. La prossima esecuzione utilizza la lista di autorizzazione aggiornata.
Vedi Network access per i livelli di accesso e la lista di autorizzazione predefinita. Le sessioni CLI locali non sono interessate da questa politica.

​
Errori di richiesta

Questi errori significano che l’API ha ricevuto la tua richiesta ma ha rifiutato il suo contenuto.

​
Prompt is too long

La conversazione più i file allegati superano la finestra di contesto del modello. 
Prompt is too long
Cosa fare:
  • Esegui /compact per riassumere i turni precedenti e liberare spazio, o /clear per ricominciare da capo
  • Esegui /context per vedere una suddivisione di cosa sta consumando la finestra: prompt di sistema, strumenti, file di memoria e messaggi
  • Disabilita i server MCP che non stai utilizzando con /mcp disable <name> per rimuovere le loro definizioni di strumenti dal contesto
  • Taglia i file di memoria CLAUDE.md grandi, o sposta le istruzioni in regole con ambito di percorso che si caricano solo quando rilevanti
  • I subagent ereditano ogni definizione di strumento MCP dalla sessione padre, che può riempire la loro finestra di contesto prima del primo turno. Disabilita i server MCP che non stai utilizzando prima di generare subagent.
  • L’auto-compact è attivo per impostazione predefinita e normalmente previene questo errore. Se hai impostato DISABLE_AUTO_COMPACT, riabilitalo o esegui /compact manualmente prima che la finestra si riempia.
Vedi Esplora la finestra di contesto per una vista interattiva di come il contesto si riempie.

​
Error during compaction: Conversation too long

/compact stesso non è riuscito perché non c’è abbastanza contesto libero per contenere il riassunto che produce. 
Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.
Questo può accadere quando la finestra è già piena nel momento in cui auto-compact si attiva, o quando esegui /compact dopo aver visto Prompt is too long. Cosa fare:
  • Premi Esc due volte per aprire l’elenco dei messaggi e tornare indietro di diversi turni. Questo elimina i messaggi più recenti dal contesto. Quindi esegui /compact di nuovo.
  • Se tornare indietro non libera abbastanza spazio, esegui /clear per avviare una sessione nuova. La tua conversazione precedente viene preservata e può essere riaperta con /resume.

​
Request too large

Il corpo della richiesta grezzo ha superato il limite di byte dell’API prima della tokenizzazione, solitamente a causa di un file incollato grande o di un allegato. 
Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.
Questo è un limite di dimensione sulla richiesta HTTP, separato dal limite della finestra di contesto. Cosa fare:
  • Premi Esc due volte e torna indietro oltre il turno che ha aggiunto il contenuto di dimensioni eccessive
  • Fai riferimento ai file grandi per percorso invece di incollare i loro contenuti, in modo che Claude possa leggerli in blocchi
  • Per le immagini, vedi Image was too large sottostante

​
Image was too large

Un’immagine incollata o allegata supera i limiti di dimensione o dimensione dell’API. 
Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size
L’immagine rimane nella cronologia della conversazione dopo l’errore, quindi ogni messaggio successivo fallisce con lo stesso errore fino a quando non la rimuovi. Cosa fare:
  • Premi Esc due volte e torna indietro oltre il turno in cui l’immagine è stata aggiunta
  • Ridimensiona l’immagine prima di incollarla. L’API accetta immagini fino a 8000 pixel sul bordo più lungo per una singola immagine, o 2000 pixel quando molte immagini sono nel contesto.
  • Fai uno screenshot più stretto della regione rilevante invece dello schermo intero

​
Unable to resize image

Claude Code non poteva ridimensionare un’immagine allegata prima di inviarla all’API. 
Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Claude Code normalmente ridimensiona automaticamente le immagini grandi. Questi errori significano che il processore di immagini nativo non è riuscito a caricarsi o ha restituito un errore, quindi l’immagine non poteva essere ridimensionata per rientrare nei limiti dell’API. Cosa fare:
  • Se il messaggio ti chiede di convertire l’immagine, convertila in PNG, JPEG, GIF, o WebP e allegala di nuovo. Claude Code può verificare le dimensioni per questi formati senza il processore di immagini.
  • Se il messaggio segnala un limite di dimensione o dimensione, ridimensiona o ricomprimi l’immagine al di sotto di quel limite prima di allegare.

​
PDF errors

Il PDF che hai allegato non poteva essere elaborato. 
PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.
Cosa fare:
  • Per i PDF di dimensioni eccessive, chiedi a Claude di leggere un intervallo di pagine con lo strumento Read invece di allegare l’intero file, o estrai il testo con uno strumento come pdftotext e fai riferimento al file di output per percorso
  • Per i PDF protetti o non validi, rimuovi la password o ri-esporta il file dall’applicazione sorgente, quindi riprova

​
Extra inputs are not permitted

Un proxy o un gateway LLM tra Claude Code e l’API ha rimosso l’intestazione della richiesta anthropic-beta, quindi l’API ha rifiutato i campi che dipendono da essa. 
API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header
Claude Code invia campi solo beta come context_management, effort e input_examples dello strumento insieme a un’intestazione anthropic-beta che li abilita. Quando un gateway invia il corpo ma elimina l’intestazione, l’API vede campi che non riconosce. Cosa fare:

​
There’s an issue with the selected model

Il nome del modello configurato non è stato riconosciuto o il tuo account manca di accesso ad esso. A partire da v2.1.160 il suggerimento finale, mostrato qui nella sua forma interattiva, varia in base alla superficie. 
There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.
Cosa fare:
  • CLI interattiva: esegui /model per scegliere dai modelli disponibili per il tuo account.
  • Modalità non interattiva (-p): passa --model con un alias o ID valido, o imposta ANTHROPIC_MODEL. Il testo di errore mostra Run --model su questa superficie.
  • Agent SDK: il testo di errore omette il suggerimento perché il modello è impostato a livello di programmazione. Imposta model su Options in TypeScript o ClaudeAgentOptions(model=...) in Python, e gestisci l’errore strutturato model_not_found per visualizzare il tuo ritentativo o selettore di modello.
  • Usa un alias come sonnet o opus invece di un ID completamente versionato. Gli alias tracciano l’ultima versione in modo che non diventino obsoleti. Vedi Configurazione del modello.
  • Se il modello sbagliato continua a tornare nella CLI, un ID obsoleto è impostato da qualche parte. Controlla in ordine di priorità: il flag --model, la variabile di ambiente ANTHROPIC_MODEL, quindi il campo model in .claude/settings.local.json, il tuo .claude/settings.json del progetto, e ~/.claude/settings.json. Rimuovi il valore obsoleto e Claude Code ricade sul tuo account predefinito.
  • Per le distribuzioni Vertex AI, vedi Risoluzione dei problemi di Vertex AI.

​
Claude Opus is not available with the Claude Pro plan

Il tuo piano di abbonamento attivo non include il modello che hai selezionato. 
Claude Opus is not available with the Claude Pro plan · Select a different model in /model
Cosa fare:
  • Esegui /model e seleziona un modello che il tuo piano include
  • Se hai aggiornato il tuo piano di recente e vedi ancora questo, esegui /logout quindi /login. Il token memorizzato riflette il tuo piano al momento dell’accesso, quindi l’aggiornamento sul web non ha effetto in una sessione esistente fino a quando non ti ri-autentichi.
  • Vedi claude.com/pricing per quali modelli ogni piano include

​
thinking.type.enabled is not supported for this model

La tua versione di Claude Code è più vecchia del minimo per Opus 4.7 o Opus 4.8. La CLI ha inviato una configurazione di thinking che il modello non accetta più. 
API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
Cosa fare:
  • Esegui claude update e riavvia Claude Code. Opus 4.7 ha bisogno di v2.1.111 o successivo. Opus 4.8 ha bisogno di v2.1.154 o successivo
  • Se non puoi aggiornare, esegui /model e seleziona Opus 4.6 o Sonnet
  • Se colpisci questo nell’Agent SDK, vedi Risoluzione dei problemi dell’SDK

​
Thinking budget exceeds output limit

Il budget di thinking esteso configurato supera la lunghezza massima della risposta, quindi non c’è spazio rimasto per la risposta effettiva. 
API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
Claude Code regola questi valori automaticamente sull’API Anthropic. Tipicamente vedi questo errore su Amazon Bedrock o Google Vertex AI quando MAX_THINKING_TOKENS è impostato più alto del limite di output del provider, o quando plan mode aumenta il budget di thinking. Cosa fare:

​
Tool use or thinking block mismatch

La cronologia della conversazione ha raggiunto l’API in uno stato incoerente, solitamente dopo che una chiamata di strumento è stata interrotta o un turno è stato modificato a metà flusso. 
API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified
Tutte e tre le varianti significano la stessa cosa: la sequenza di blocchi tool_use, tool_result e thinking nella cronologia non corrisponde più a quello che l’API si aspetta. Cosa fare:
  • Se stai utilizzando Opus 4.7 o Opus 4.8, esegui prima claude update. Le versioni precedenti a v2.1.156 possono attivare questo errore durante l’uso normale dello strumento, e /rewind non lo cancella.
  • Esegui /rewind, o premi Esc due volte, per tornare indietro a un checkpoint prima del turno corrotto e continua da lì. Vedi Checkpointing per come i checkpoint vengono creati e ripristinati.

​
Usage Policy refusal

L’API ha rifiutato di rispondere perché il contenuto nella conversazione ha attivato un controllo della Usage Policy. Il messaggio include un ID di richiesta che puoi citare al supporto se ritieni che il rifiuto sia errato. 
API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.
Il controllo valuta l’intera conversazione, non solo il tuo ultimo prompt, quindi inviare un nuovo messaggio nella stessa sessione di solito ri-attiva lo stesso rifiuto. Lo stesso vale dopo aver chiuso e riaperto la sessione con --continue o --resume, poiché la trascrizione su disco contiene ancora il contenuto che ha attivato il rifiuto. Cosa fare:
  • Premi Esc due volte o esegui /rewind per tornare indietro a un checkpoint prima del turno che ha attivato il rifiuto, quindi riformula o prendi un approccio diverso. Vedi Checkpointing.
  • Se non riesci a identificare quale turno l’ha causato, esegui /clear per avviare una conversazione nuova nello stesso progetto. La tua conversazione precedente viene preservata su disco e rimane disponibile in /resume.
  • In modalità non interattiva (-p), dove rewind non è disponibile, riprova con un prompt riformulato o avvia una nuova sessione senza --continue.

​
Le risposte sembrano di qualità inferiore al solito

Se le risposte di Claude sembrano meno capaci di quanto vi aspettiate ma nessun errore è mostrato, la causa è solitamente lo stato della conversazione piuttosto che il modello stesso. Claude Code non cambia silenziosamente le versioni del modello. Può passare a un modello di fallback in casi specifici come una quota Opus raggiunta o una regione Bedrock o Vertex AI che manca il vostro modello; il controllo Model selection sottostante cattura entrambi, e Model configuration spiega quando si applica il fallback. Controllate questi prima:
  • Model selection: eseguite /model per confermare che siete sul modello che vi aspettate. Una scelta /model precedente o una variabile di ambiente ANTHROPIC_MODEL potrebbe avervi su un modello più piccolo di quello che intendavate.
  • Effort level: eseguite /effort per controllare il livello di ragionamento attuale e aumentatelo per il debug difficile o il lavoro di progettazione. I valori predefiniti variano per modello, quindi controllate prima di assumere che siete sotto il massimo. Vedete Adjust effort level per i valori predefiniti per modello e il collegamento ultrathink.
  • Context pressure: eseguite /context per vedere quanto è piena la finestra. Se è vicina alla capacità, eseguite /compact a un punto naturale o /clear per ricominciare da capo. Vedete Explore the context window per come auto-compact influisce sui turni precedenti.
  • Stale instructions: i file CLAUDE.md grandi o obsoleti e le definizioni di strumenti MCP consumano contesto e possono dirigere le risposte. /doctor contrassegna i file di memoria di dimensioni eccessive e le definizioni di subagent; /context mostra l’utilizzo di token dello strumento MCP.
Quando una risposta va male, il rewind di solito funziona meglio che rispondere con correzioni. Premete Esc due volte o eseguite /rewind per tornare indietro a prima del turno cattivo, quindi riformulate il prompt con più specifiche. Correggere nel thread mantiene il tentativo sbagliato nel contesto, che può ancorare le risposte successive ad esso. Vedete Checkpointing. Se la qualità sembra ancora non corretta dopo aver controllato quanto sopra, eseguite /feedback e descrivete cosa vi aspettavate rispetto a quello che avete ottenuto. Il feedback inviato in questo modo include la trascrizione della conversazione, che è il modo più veloce per Anthropic per diagnosticare una regressione reale. Vedete Report an error se /feedback non è disponibile nel vostro ambiente.

​
Segnalare un errore

Questa pagina copre gli errori dall’API Claude. Per gli errori da altri componenti di Claude Code, vedi la guida rilevante: Se un errore non è elencato qui o la correzione suggerita non aiuta:
  • Esegui /feedback all’interno di Claude Code per inviare la trascrizione e una descrizione ad Anthropic. Il comando offre anche di aprire un problema GitHub precompilato. Su Bedrock, Vertex AI, Foundry e altri provider di terze parti, /feedback salva un archivio locale che puoi inviare al tuo rappresentante dell’account Anthropic.
  • Esegui /doctor per controllare i problemi di configurazione locale
  • Controlla status.claude.com per gli incidenti attivi
  • Cerca i problemi esistenti su GitHub