Gli errori dell'API Claude spiegati: errore del server 500, sovraccarico 529, limite di frequenza 429, richiesta non valida 400 — e la soluzione per ciascuno

Ogni sviluppatore che usa l'API di Claude prima o poi incontra degli errori. Alcuni dipendono da te (richieste malformate), altri da Anthropic (problemi del server) e altri ancora dall'architettura (limiti di frequenza durante un uso intensivo). Questa guida tratta tutti i codici di errore comuni dell'API di Claude, con cause reali, soluzioni concrete e logiche per i nuovi tentativi pronte per la produzione. Spiega inoltre come l'instradamento tramite un gateway con più account a monte possa ridurre la frequenza degli errori dovuti ai limiti di frequenza e al sovraccarico.

Verifica l'accesso e il modello prima di riprovare

Conferma che l'accesso tramite il tuo piano o saldo sia attivo, controlla il gruppo di chiavi e usa un modello restituito per quella chiave. Una risposta corretta alla richiesta dell'elenco dei modelli è una verifica iniziale; verifica una piccola richiesta di generazione prima di avviare un'esecuzione più ampia dell'agente.

Usa modelli e gruppi di chiavi e l'impostazione checklist di configurazione dell'agente per distinguere i problemi di accesso da quelli di configurazione degli strumenti e dagli errori a monte.

"Errore del server Claude": quale stai effettivamente riscontrando?

"Errore del server Claude" è ciò che le persone digitano quando l'API smette di rispondere, ma è il numero nel messaggio a determinare cosa fare. Un **500** indica un errore interno dell'API: attendi, riprova o cambia modello. Un **529** indica che il modello è saturo per tutti: la procedura è la stessa e il problema si risolve da solo. Un **429** indica che hai raggiunto un limite: rallenta o riduci le richieste parallele.

Un **400** significa che la richiesta stessa è stata rifiutata: ripetere lo stesso tentativo fallirà di nuovo. Cerca il tuo codice qui sotto; ogni sezione riporta il messaggio esatto, la causa e la soluzione. Se visualizzi l'errore in Claude Code anziché nel tuo codice, le guide agli errori di Claude Code su /claude-code/errors/ trattano i messaggi specifici della CLI (timeout OAuth, "processo terminato con codice 1", uso concorrente degli strumenti).

Errore 400 — Richiesta non valida

Un errore 400 significa che la tua richiesta non è valida dal punto di vista strutturale. L'API di Claude l'ha rifiutata prima ancora di tentare di generare una risposta. Il corpo dell'errore contiene un messaggio che spiega cosa non va: leggilo sempre con attenzione. Le cause comuni includono: l'array messages è vuoto o malformato, il campo content è null anziché una stringa, max_tokens supera il limite del modello, l'identificatore del modello non esiste, il prompt di sistema è nel formato sbagliato oppure le definizioni degli strumenti contengono errori nello schema.

L'errore 400 più frequente per gli utenti di Claude Code è il superamento della lunghezza del contesto. Quando la cronologia della conversazione supera la finestra di contesto del modello (200K token per la maggior parte dei modelli Claude), l'API restituisce un 400 con un messaggio che indica che l'input è troppo lungo. La soluzione consiste nell'usare /compact per riassumere la cronologia, rimuovere dal contesto i contenuti di file di grandi dimensioni oppure avviare una nuova sessione. Non è un limite di frequenza: è un vincolo rigido sulla dimensione della richiesta.

Un altro errore 400 comune è l'invio di un parametro o di una versione del modello non supportati. Se hai aggiornato di recente il tuo SDK o modificato gli identificatori dei modelli, verifica attentamente che ogni campo della richiesta corrisponda alla specifica API attuale. Gli ID dei modelli distinguono tra maiuscole e minuscole e sono specifici per versione: 'claude-opus-4-6' è valido, ma 'Claude-Opus-4.6' non lo è. In caso di dubbi, interroga l'endpoint /v1/models per vedere esattamente quali identificatori accetta il fornitore.

Errore 400 - "L'input è troppo lungo per il modello richiesto"

Questo specifico errore 400 significa che la tua richiesta (prompt di sistema + messaggi + eventuali definizioni degli strumenti) supera la finestra di contesto del modello. Non è un limite di frequenza e riprovare non risolverà il problema: lo stesso payload fallirà ogni volta finché non riduci l'input o passi a un modello con una finestra di contesto più ampia.

Tre soluzioni pratiche, in ordine di impegno richiesto: innanzitutto, riduci la cronologia della conversazione che invii nuovamente; alla maggior parte delle app di chat bastano gli ultimi scambi e un riepilogo aggiornato, non l'intera trascrizione. Poi, conta i token prima dell'invio (l'endpoint per il conteggio dei token è gratuito) e imponi nel codice un budget massimo per l'input. Infine, se hai davvero bisogno dell'intero contesto, come repository completi o documenti lunghi quanto un libro, passa a un modello con contesto da 1M, come Fable 5, nel quale la stessa richiesta rientra comodamente.

Un problema comune negli strumenti basati su agenti: le sessioni prolungate accumulano risultati degli strumenti e contenuti dei file finché un ulteriore scambio porta la richiesta oltre il limite. Se l'errore compare a metà sessione in Claude Code o in un agente simile, compatta o cancella il contesto della sessione anziché accorciare il prompt.

Errore 429 — "Limite di frequenza raggiunto" / "Frequenza superata"

La stessa condizione si presenta con due formulazioni. L'API restituisce HTTP 429 con rate_limit_error; claude.ai e Claude Code lo mostrano come "frequenza superata" o "limite di frequenza raggiunto". Qualunque sia il testo visualizzato, la causa è identica: il tuo account ha esaurito la quota disponibile per la finestra temporale corrente e le richieste vengono rifiutate finché la quota non si ripristina.

Un 429 significa che hai superato la frequenza di richieste consentita. La risposta include un'intestazione Retry-After che indica quanti secondi attendere prima di riprovare. I limiti di frequenza di Anthropic operano su più dimensioni: richieste al minuto (RPM), token al minuto (TPM) e token al giorno (TPD). Raggiungere uno qualsiasi di questi limiti genera un 429. Il messaggio di errore di solito indica quale limite è stato raggiunto.

Per gli utenti di Claude Code, i limiti di frequenza sono l'errore più frustrante perché interrompono il flusso di lavoro. Un singolo sviluppatore che esegue Claude Code con sottoagenti può facilmente raggiungere i limiti RPM durante operazioni parallele, oppure i limiti TPM durante sessioni con file di grandi dimensioni nel contesto. I limiti variano in base al livello dell'account: i livelli inferiori hanno limiti più rigidi, che un uso intensivo degli agenti supera regolarmente.

La risposta corretta a un errore 429 è un backoff esponenziale con jitter. Attendi per il tempo indicato da Retry-After, quindi aggiungi un ritardo casuale per evitare un'ondata di richieste simultanee se più client raggiungono il limite nello stesso momento. Un gateway come AI Prime Tech Unlimited aiuta a ridurre gli errori 429 instradando le richieste su più account a monte, moltiplicando di fatto la quota disponibile entro i limiti di frequenza. Quando un account a monte raggiunge il limite di frequenza, il gateway instrada le richieste verso un altro.

Errore 500 — Errore interno del server

Un errore 500 indica che qualcosa è andato storto lato server: non è colpa tua e non puoi risolverlo modificando la richiesta. Questi errori sono transitori: la stessa richiesta che ha restituito un 500 probabilmente riuscirà se la ripeti dopo una breve attesa. L'infrastruttura di Anthropic restituisce occasionalmente errori 500 durante i rilasci, le modifiche alla capacità o le interruzioni dei servizi interni.

La gestione corretta degli errori 500 consiste semplicemente nel riprovare con backoff. Attendi 1-2 secondi e ripeti esattamente la stessa richiesta. Se fallisce di nuovo, attendi 4 secondi, poi 8, fino a un massimo di circa 60 secondi. La maggior parte degli errori 500 si risolve al primo tentativo successivo. Se continui a ricevere errori 500 per più di qualche minuto, controlla la pagina di stato di Anthropic o l'endpoint di stato del gateway per verificare la presenza di incidenti noti.

Non modificare la richiesta in risposta a un errore 500: il problema è lato server. Cambiare il prompt, ridurre il contesto o cambiare modello non aiuta e fa perdere tempo di sviluppo nel debug di un problema che non dipende da te. Le uniche azioni da intraprendere sono: riprovare, attendere più a lungo se i nuovi tentativi falliscono e inviare un avviso se il problema persiste oltre un intervallo ragionevole (5-10 minuti di errori continui).

Errore 529 — "Il server di Claude è sovraccarico" (overloaded_error)

Il codice di stato 529 è specifico di Anthropic e indica che l'API sta registrando una domanda elevata: il modello richiesto ha temporaneamente raggiunto la capacità massima. A differenza di un 429 (che indica che è stato superato il limite di frequenza di YOUR), un 529 significa che SYSTEM è sovraccarico indipendentemente dai tuoi limiti individuali. Non hai fatto nulla di sbagliato; in quel momento la domanda supera semplicemente la capacità di calcolo disponibile.

Gli errori 529 sono più comuni nelle ore di punta (durante l'orario lavorativo negli Stati Uniti), subito dopo il rilascio di nuovi modelli (tutti provano il nuovo modello contemporaneamente) e nei momenti di grande diffusione virale, quando l'utilizzo aumenta improvvisamente per tutti i clienti. Sono meno comuni con Sonnet e Haiku che con Opus, perché Opus richiede più capacità di calcolo per richiesta e ha vincoli di capacità più stringenti.

Gestisci gli errori 529 con un backoff più lungo rispetto agli errori 500. Inizia con un'attesa di 5-10 secondi e aumentala in modo esponenziale. Se stai sviluppando sistemi di produzione, valuta un modello di fallback: quando Opus restituisce 529, usa Sonnet per quella richiesta. Anche un gateway con più account a monte può aiutare: il sovraccarico può incidere in modo diverso sui livelli di priorità dei vari account, offrendo al gateway più opzioni di instradamento durante i picchi di domanda.

"Nessun upstream disponibile" — Un errore dell'infrastruttura, non di Claude

"Nessun upstream disponibile" non viene restituito dall'API di Claude stessa. È il messaggio generato da un bilanciatore di carico o da un proxy di ingresso (in genere Envoy) quando tutte le istanze backend che si trovano dietro di esso non sono disponibili. Lo vedrai su claude.ai durante un'interruzione del servizio e su qualsiasi proxy o gateway il cui pool di connessioni a monte sia esaurito o non superi i controlli di integrità.

Non c'è nulla da correggere nel tuo codice. Trattalo come un problema transitorio: controlla status.anthropic.com, attendi e riprova con backoff esponenziale, esattamente come faresti per un 529. Se persiste per più di qualche minuto sull'endpoint ufficiale, si tratta di un'interruzione del servizio; se proviene da un gateway di terze parti, quel gateway ha perso tutta la propria capacità a monte.

Questo è uno dei tipi di errore che un gateway con più account è progettato per assorbire: quando un account a monte è soggetto a limitazioni o non è operativo, la richiesta viene instradata verso un altro account invece di restituirti l'errore.

Logica di ripetizione delle richieste pronta per la produzione

Una buona logica di ripetizione delle richieste gestisce tutti gli errori transitori (429, 500, 529) in modo uniforme, con backoff esponenziale e jitter, e considera gli errori permanenti (400, 401, 403) come non ripetibili. Lo schema è: inviare la richiesta, controllare il codice di stato, se l'errore consente un nuovo tentativo attendere con backoff e riprovare fino a N volte, altrimenti sollevare immediatamente un'eccezione. Per la maggior parte delle applicazioni, il numero massimo di nuovi tentativi dovrebbe essere 3-5.

Il jitter evita che i nuovi tentativi siano sincronizzati. Se dieci client raggiungono un limite di frequenza nello stesso momento e tutti riprovano dopo esattamente 2 secondi, falliranno di nuovo tutti contemporaneamente. Aggiungere jitter casuale (moltiplicando il ritardo per un fattore casuale compreso tra 0.5 e 1.5) distribuisce i nuovi tentativi nel tempo e migliora notevolmente il tasso di successo. Ogni client dell'API di Claude in produzione dovrebbe includere il jitter.

Per Claude Code e i flussi di lavoro agentici, implementa la logica di ripetizione a livello del client HTTP, così le singole chiamate agli strumenti e le richieste dei sottoagenti ne beneficiano automaticamente. L'SDK di Anthropic include già una logica di base per i nuovi tentativi, ma potresti voler personalizzare i timeout e il numero massimo di tentativi per il tuo caso d'uso. Se usi AI Prime Tech Unlimited, il gateway gestisce internamente i nuovi tentativi a monte e l'instradamento, riducendo fin dall'inizio gli errori che arrivano al tuo client.

Come un gateway riduce questi errori

Un gateway ben progettato come AI Prime Tech Unlimited riduce la frequenza degli errori in diversi modi. Per i limiti di frequenza (429), il gateway distribuisce le richieste su più account API a monte, quindi il tuo limite di frequenza effettivo è la somma di quelli di tutti gli account a monte anziché la quota assegnata a un singolo account. Per gli errori di sovraccarico (529), il gateway può riprovare su altri account a monte che possono avere livelli di priorità o posizioni in coda diversi.

Per gli errori del server (500), il gateway può riprovare in modo trasparente prima di restituire l'errore al tuo client: ricevi una risposta leggermente più lenta invece di un errore. Per gli errori 400, il gateway non può aiutare perché è la richiesta stessa a non essere valida, ma i gateway ben progettati forniscono messaggi di errore più chiari che ti aiutano a eseguire il debug più rapidamente rispetto alle risposte di errore grezze di Anthropic.

Il risultato per gli sviluppatori è un minor numero di errori che raggiungono l'applicazione, una minore necessità di logica di ripetizione lato client e prestazioni più stabili nelle ore di punta. Questo è particolarmente utile per le sessioni di Claude Code, dove un errore durante un'attività può interrompere il flusso di lavoro, e per le applicazioni di produzione, dove il tasso di errore influisce direttamente sull'esperienza utente. La tariffa fissa del piano illimitato significa che questi nuovi tentativi e reinstradamenti non comportano costi aggiuntivi.

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.