Errori di Claude Code e come risolverli

Guide dettagliate per ogni errore

• Errore API: 500 (errore interno del server) — interruzioni del servizio, guasti di singoli modelli, compattazione al 0%.
• Sovraccarico / errore API 529 — capacità, nuovi tentativi, picchi di richieste dei sottoagenti.
• Errore API 400 — prompt troppo lungo, concorrenza nell'uso degli strumenti e altre richieste rifiutate.
• Errori OAuth — timeout di 15000ms superato, codice di stato 500 durante l'accesso.
• Processo terminato con codice 1 — arresti anomali dell'estensione di VS Code e dell'app desktop.
• Limite di frequenza raggiunto / 429 — i tre limiti e come aumentarli.
• Prompt troppo lungo / limite di contesto raggiunto — cosa riempie la finestra, falsi allarmi, errori di compattazione, limiti di lunghezza claude.ai.
• Limite di utilizzo raggiunto — finestre di utilizzo della sessione, settimanali e di Opus, "limiti di utilizzo API specificati", "saldo crediti troppo basso".
• Autenticazione 401 / 403 — credenziali non valide, chiave API non valida, "accesso non effettuato", host_not_allowed.
• Errori di connessione — ECONNRESET, "in attesa della risposta API", certificati, proxy, variabili per i nuovi tentativi.
• Si blocca, resta fermo, non risponde — dove si blocca, tasti per uscire, bug noti che causano blocchi, memoria.
• claude.ai non funziona — "si è verificato un errore", vincoli di capacità, limite di 5 ore, errori di accesso.

Errore API 500 (e 529 per sovraccarico)

Un 500 indica un guasto a monte; 529 è il codice esplicito di Anthropic per "modello al limite della capacità". Nessuno dei due è causato dal tuo prompt. Claude Code riprova autonomamente alcune volte; se rinuncia, attendi un minuto e riprendi con claude -c. Cambiare livello con /model spesso funziona immediatamente perché la capacità è specifica per ogni modello. Su questo gateway, se un account a monte è saturo, il traffico viene trasferito automaticamente a un altro: ecco perché gli errori 529 sono più rari qui che con un singolo account.

Errore API 400 — richiesta non valida / contesto troppo lungo

In Claude Code, un 400 significa quasi sempre che la conversazione e i file letti non rientrano più nella finestra di contesto del modello. /compact riassume la cronologia; /clear ricomincia da zero; oppure passa a una (1M) variante del modello. Altri errori 400: un parametro non supportato dopo un aggiornamento (esegui claude update), oppure un'immagine o un file che il modello non può accettare.

Errore API 429 — limite di frequenza / frequenza superata

Si applicano tre limiti: richieste al minuto, token al minuto e richieste simultanee. Le sessioni con agenti raggiungono prima il limite di concorrenza: ogni sottoagente è una richiesta parallela in streaming che occupa uno slot fino al completamento. Riduci il parallelismo, attendi il tempo indicato da retry-after e, per un lavoro prolungato, richiedi un limite di concorrenza più alto per il tuo account del gateway.

Errore OAuth: timeout di 15000ms superato

La procedura /login non è riuscita a raggiungere il servizio di autenticazione di Anthropic entro 15 secondi. È un problema di rete, non dell'account: un proxy aziendale, una VPN che interrompe il callback o una regione in cui l'endpoint di autenticazione è lento. Riprova una volta; se il problema persiste, imposta HTTPS_PROXY per la tua rete, oppure evita del tutto OAuth usando una chiave API: con ANTHROPIC_API_KEY (e ANTHROPIC_BASE_URL per un gateway), Claude Code non avvia mai la procedura di accesso.

Errore OAuth: richiesta fallita con codice di stato 500

Il servizio di autenticazione ha risposto con un errore del server durante l'accesso o il rinnovo del token. La causa non è dalla tua parte; attendi qualche minuto ed esegui nuovamente /login. Se devi lavorare subito, l'accesso tramite chiave API descritto sopra aggira OAuth, e claude setup-token su una macchina dove l'accesso funziona produce un token di lunga durata che puoi trasferire su quella dove non funziona.

Errore: processo di Claude Code terminato con codice 1

È l'estensione dell'IDE o l'app desktop a segnalare che la CLI avviata si è arrestata in modo anomalo all'avvio: l'errore effettivo si trova al livello sottostante. Apri un terminale ed esegui claude direttamente: vedrai il messaggio effettivo, che quasi sempre riguarda una versione di Node.js precedente a 18, un PATH danneggiato dopo un'installazione tramite npm, un'installazione nativa corrotta o un file settings.json con JSON non valido (una virgola fuori posto in un blocco di hook è un classico). claude doctor verifica i primi tre; un linter per JSON rileva il quarto. Reinstallare con il programma di installazione nativo risolve la maggior parte degli altri problemi.

401 / errori di autenticazione

invalid x-api-key o authentication_error significa che la chiave non appartiene all'endpoint. Se ANTHROPIC_BASE_URL punta al gateway, la chiave deve essere una chiave del gateway; una chiave della console Anthropic verrà rifiutata, e vale anche il contrario. /status mostra quali endpoint e chiave sono attivi. Se usi /login e una chiave API contemporaneamente, prevale la chiave. I cicli di rinnovo del token, Not logged in dopo un accesso riuscito e gli errori 403 dei proxy sono trattati nella pagina 401 / 403.

"Nessun upstream funzionante"

Non è un errore API: è il bilanciatore di carico davanti a un servizio che segnala l'assenza di backend disponibili. Sull'endpoint ufficiale indica un'interruzione del servizio; su un gateway significa che l'intero pool a monte è inattivo o soggetto a limitazioni. Attendi e riprova; non modificare la configurazione.

Claude Code non funziona affatto

• Si avvia e poi si chiude senza messaggi → esegui claude /doctor; di solito è un problema della versione di Node o di PATH.
• Si blocca all'avvio o durante la sessione → vedi blocchi e sessioni ferme e errori di connessione.
• command not found → vedi la guida all'installazione.
• Gli strumenti non funzionano a causa di errori di autorizzazione → /permissions, oppure --allowedTools negli script.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Domande frequenti

AI Prime Tech è un gateway API indipendente e non è affiliato ad Anthropic, né approvato o sponsorizzato da Anthropic. «Claude» e «Claude Code» sono marchi di Anthropic. Le funzionalità di Claude Code descritte qui rispecchiano la documentazione pubblica di Anthropic al momento della stesura e cambiano frequentemente; i prezzi e gli elenchi dei modelli presenti in questa pagina vengono letti dalle impostazioni attuali di questo gateway.