Limiti di Claude: cosa fare quando li raggiungi

Quali sono i limiti di utilizzo di Claude?

I limiti di utilizzo di Claude sono gestiti da due sistemi distinti. Il primo passo consiste nel capire quale dei due ha bloccato la richiesta. Un abbonamento Claude (Pro, Max, Team o Enterprise) fornisce una quota di utilizzo su finestra mobile, condivisa tra i modelli e con la chat di Claude. Quando la quota è esaurita, viene visualizzato un messaggio come You've hit your session limit · resets 3:45pm. L'API di Claude misura invece la velocità di invio di richieste e token, conteggiata al minuto. In caso di superamento, restituisce un errore HTTP 429 di tipo rate_limit_error e un'intestazione retry-after che indica quanti secondi attendere.

Le soluzioni sono completamente diverse. Il limite dell'abbonamento dipende dalla quantità utilizzata durante una finestra temporale: occorre attendere il ripristino della quota oppure acquistare ulteriore utilizzo. Il rate limit dell'API dipende invece dalla velocità corrente delle richieste e viene rimosso dopo pochi secondi, quando si riduce la frequenza di invio.

Le quote dei piani e i numeri dei tier dei rate limit cambiano spesso. Un numero errato sarebbe peggiore di nessun numero, quindi qui non ne sono riportati. Leggi i tuoi valori con i comandi riportati più avanti.

Quale limite hai raggiunto? Leggi il messaggio esatto

Claude Code indica il sistema nel testo visualizzato. Identifica il tuo prima di modificare qualsiasi impostazione.

• You've hit your session limit · resets 3:45pm è un limite dell'abbonamento. Hai esaurito la quota disponibile per il tuo piano nella finestra temporale corrente.
• You've hit your weekly limit · resets Mon 12:00am riguarda lo stesso sistema, ma su una finestra temporale più lunga.
• You've hit your Opus limit · resets 3:45pm è un limite dell'abbonamento applicato solo alle richieste a Opus. Questo è l'unico caso in cui cambiare modello è utile.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. è un limite di frequenza dell'API. Hai raggiunto il limite configurato per la tua chiave API oppure per il progetto Amazon Bedrock o Google Cloud. Il limite applicabile dipende da come il client esegue l'autenticazione, perché un client Bedrock o Vertex viene conteggiato nella quota del progetto cloud e non in quella di un'organizzazione Anthropic.
• API Error: Server is temporarily limiting requests (not your usage limit) è una limitazione temporanea indipendente dalla quota del piano. Claude Code ritenta automaticamente la richiesta con un backoff prima di visualizzare questa riga.

Limiti dell’abbonamento: sessione, settimana e finestra Opus

Un piano di abbonamento include una quota di utilizzo a scorrimento. Quando la quota è esaurita, Claude Code blocca le richieste successive fino all’orario di ripristino indicato nel messaggio. Due proprietà di questa quota causano la maggior parte dei dubbi.

• È condivisa con Claude chat. Il lavoro svolto su claude.ai utilizza la stessa quota del lavoro eseguito nel terminale, quindi un pomeriggio intenso in chat riduce il tempo disponibile per programmare la sera. Tutte le interfacce a cui accedi con quell’account utilizzano lo stesso pool; su Linux, l’app desktop beta e la CLI Claude Code consumano un’unica quota condivisa, non una quota ciascuna.
• È condivisa tra i modelli. I limiti di sessione e settimanali non prevedono una quota separata per modello. L’unica eccezione è il limite Opus.

Su Claude for Teams ed Enterprise, la struttura documentata prevede una quota per postazione che si ripristina su una finestra mobile di cinque ore e su una finestra settimanale. La quota è condivisa con Claude chat e Cowork e varia in base al livello della postazione (Standard o Premium). Su Pro e Max, l’orario di ripristino visualizzato nel messaggio e le tue barre /usage sono i dati affidabili. Non usare come riferimento un valore copiato da un articolo di blog. Se devi ancora scegliere un livello, quale piano Claude ti serve confronta ciò che abilita ciascuna opzione.

Perché il cambio di modello con /model non ripristina l'accesso

È l'errore più comune. La documentazione è chiara: i limiti della sessione e quelli settimanali sono condivisi da tutti i modelli, quindi cambiare modello non ripristina l'accesso. Se la finestra della sessione è esaurita, scegliere un modello più piccolo cambia quale modello risponderebbe. Non cambia però la quota disponibile, perché la quota non è mai stata assegnata per modello. Di conseguenza, il cambio non può liberare alcuna quota.

L'eccezione è il limite Opus, che è effettivamente specifico del modello. Se il messaggio visualizzato è You've hit your Opus limit, la correzione consiste in /model. Passa a un altro modello e continua a lavorare, perché sono state bloccate soltanto le richieste a Opus.

Considerare il limite un bug è il secondo errore. Reinstallare o eseguire nuovamente l'autenticazione non cambia nulla. La quota torna disponibile quando la finestra si reimposta oppure quando acquisti crediti per l'utilizzo.

Cosa fare quando raggiungi un limite del piano

1. Leggi l'orario di ripristino. Una finestra di sessione è breve. Una finestra settimanale non si risolve aspettando alla scrivania.
2. Se hai raggiunto il limite di Opus, esegui /model e scegli un altro modello.
3. Esegui /usage per visualizzare i limiti del piano, le barre di utilizzo e l'orario del ripristino. /cost è un alias per la stessa schermata.
4. Esegui /usage-credits per continuare a lavorare oltre il limite. Nei piani Pro e Max apre le impostazioni di fatturazione. Nei piani Team ed Enterprise apre le impostazioni di utilizzo dell'organizzazione oppure invia una richiesta agli amministratori se non disponi dell'accesso alla fatturazione.
5. Se raggiungi lo stesso limite ogni settimana, il piano non è adeguato al tuo modo di lavorare. In questo caso, conviene valutare una volta le opzioni per superare un limite di utilizzo invece di farlo a ogni ripristino.

/usage-credits richiede un abbonamento a claude.ai con accesso effettuato tramite /login. Non è disponibile con l'autenticazione tramite API key, perché un'API key non dispone di un'allocazione del piano da estendere.

I crediti di utilizzo hanno un effetto collaterale da conoscere. La durata della cache dei prompt è di un'ora con un abbonamento e scende a cinque minuti quando utilizzi i crediti. Di conseguenza, più turni iniziano senza cache e l'utilizzo dei token di Claude Code aumenta a parità di lavoro.

Messaggi che sembrano limiti di utilizzo, ma non lo sono

Quattro errori di Claude Code vengono segnalati come limiti di utilizzo, ma nessuno di questi lo è.

• Un avviso relativo al contesto o alla compattazione automatica non è un limite di utilizzo. /context stampa una riga come Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. quando la conversazione supera la finestra di contesto del modello. La cronologia meno recente viene riassunta per liberare spazio, senza modificare la quota prevista dal piano.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. indica che /compact non è riuscito, perché non è rimasto abbastanza contesto disponibile per contenere il riepilogo che dovrebbe generare.
• Credit balance is too low indica che l'organizzazione Console ha esaurito i crediti prepagati. Aggiungi crediti all'indirizzo platform.claude.com/settings/billing, dove è disponibile anche il ricaricamento automatico.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context è un controllo dei diritti di accesso, non una quota esaurita. Seleziona la variante del modello senza il suffisso [1m] oppure imposta CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Un altro errore proviene dall'API. Un errore 413 request_too_large indica un limite dimensionale per una singola richiesta, non un limite di frequenza.

Limiti di frequenza dell'API: cosa conta realmente il codice 429

La Messages API misura tre parametri, separatamente per ogni classe di modello.

• richieste al minuto (RPM)
• token di input al minuto (ITPM)
• token di output al minuto (OTPM)

La tua organizzazione ha anche un limite di spesa, che è un parametro diverso: il costo mensile massimo per l'utilizzo dell'API. Quando raggiungi il limite di spesa del tuo tier, l'utilizzo dell'API viene sospeso fino al mese successivo, a meno che tu non richieda un limite superiore. Nessun ciclo di retry può risolvere questo problema.

Quattro meccanismi determinano il momento in cui arriva il codice 429.

• I limiti sono specifici per classe di modello. Si applicano separatamente a ogni modello, quindi puoi utilizzare contemporaneamente modelli diversi fino ai rispettivi limiti. Alcune famiglie condividono lo stesso bucket: il limite di frequenza Opus è complessivo per Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5, mentre Claude Sonnet 5 ha un limite distinto.
• La capacità si ricarica continuamente. L'API utilizza un algoritmo token bucket, quindi la capacità viene reintegrata continuamente invece di azzerarsi in un momento prestabilito. Un limite di 60 richieste al minuto può essere applicato come una richiesta al secondo; pertanto, 60 richieste inviate contemporaneamente possono comunque fallire.
• Nella maggior parte dei modelli, per l'ITPM contano soltanto i token di input non memorizzati nella cache. input_tokens e cache_creation_input_tokens contano. cache_read_input_tokens non conta nella maggior parte dei modelli Claude; Claude Haiku 3.5 è l'eccezione documentata. La memorizzazione nella cache offre quindi margine aggiuntivo rispetto ai limiti di frequenza, oltre a uno sconto. Per l'output, un valore elevato di max_tokens non conta ai fini dell'OTPM, perché l'OTPM considera soltanto i token effettivamente prodotti.
• I limiti sono definiti a livello di organizzazione. A un workspace può essere assegnato un limite inferiore e i limiti a livello di organizzazione si applicano sempre, anche se la somma dei limiti dei workspace è superiore. Se non hai sovrascritto un limite in un workspace, questo viene ereditato dall'organizzazione e non viene lasciato illimitato.

I tier denominati Start, Build, Scale e Custom stabiliscono i valori effettivi. L'assegnazione avviene automaticamente in base alla cronologia di utilizzo e allo stato dell'account. Le nuove organizzazioni possono iniziare con limiti inferiori a quelli standard pubblicati, quindi il primo codice 429 può arrivare prima di quanto previsto da una tabella. Un aumento improvviso dell'utilizzo attiva i limiti di accelerazione, che restituiscono il codice 429 anche se sei ancora entro il limite del tuo tier; aumenta quindi gradualmente il traffico. Ogni valore pubblicato è un tetto massimo: i limiti documentati indicano l'utilizzo massimo consentito, non un minimo garantito. Per richiedere un limite superiore, usa il controllo "Request rate limit increase" nella pagina Limits della Claude Console.

Interpretare un 429: retry-after, header e retry degli SDK

Ogni errore API restituisce lo stesso envelope: un oggetto error annidato che contiene il tipo e il messaggio, oltre a un elemento request_id di primo livello.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

I header contengono le informazioni restanti.

• retry-after indica il numero di secondi da attendere prima di poter riprovare la richiesta. I tentativi anticipati falliscono.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining e anthropic-ratelimit-requests-reset descrivono il budget della richiesta.
• anthropic-ratelimit-input-tokens-* e anthropic-ratelimit-output-tokens-* forniscono le stesse informazioni per ITPM e OTPM, con i medesimi suffissi limit, remaining e reset.
• anthropic-ratelimit-tokens-* mostra i valori relativi al limite più restrittivo attualmente applicato.

I header di reset sono timestamp RFC 3339. I token rimanenti indicati negli header sono arrotondati al migliaio più vicino, quindi devono essere interpretati come un indicatore approssimativo. La modalità Fast dispone di un pool separato e dei propri header anthropic-fast-*. Leggili tutti da una chiamata completata correttamente:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

Ogni risposta contiene inoltre un header request-id univoco, ad esempio req_018EeWyXxfu5pfWkrYcMdjWG. Nei corpi delle risposte di errore compare come request_id, mentre nelle risposte degli SDK Python e TypeScript compare come _request_id. Riportalo quando contatti il supporto.

Prima di implementare un ciclo di backoff, verifica se ne hai davvero bisogno. Gli SDK ufficiali ritentano automaticamente gli errori temporanei, inclusi gli errori di connessione, i limiti di frequenza e gli errori del server 5xx, applicando un backoff esponenziale per impostazione predefinita due volte e rispettando l'header retry-after quando presente. Ogni client accetta un'opzione maximum-retries per modificare o disabilitare questo comportamento.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error non dipende da te

Un 429 indica che hai inviato richieste troppo rapidamente. Un 529 overloaded_error indica che l'API è temporaneamente sovraccarica. Può verificarsi quando l'API riceve molto traffico da tutti gli utenti. La causa non è la tua chiave né il tuo codice. Riprova con un backoff esponenziale. Gli SDK lo applicano già alle risposte 5xx. Se il problema non si risolve, controlla status.claude.com. Un 500 api_error indica un errore interno. Devi riprovare allo stesso modo. Nessuno dei due codici indica un limite di frequenza.

Leggi i tuoi limiti invece di una tabella

Con un abbonamento, /usage è la schermata più importante. Mostra le barre relative all'utilizzo del piano e una suddivisione degli elementi che le hanno consumate. d o w alterna la visualizzazione tra le ultime 24 ore e gli ultimi 7 giorni. Sono necessarie due precisazioni. Il blocco Session mostra l'utilizzo dei token API ed è destinato agli utenti dell'API; gli abbonati possono quindi ignorare il relativo importo in dollari. I valori provengono dalla cronologia locale delle sessioni su quel computer, quindi non includono l'utilizzo effettuato da un altro dispositivo o da claude.ai.

Sul lato API, la pagina Usage nella Claude Console mostra due grafici: "Rate Limit - Input Tokens" e "Rate Limit - Output Tokens". Il grafico degli input rappresenta il valore massimo orario dei token di input non memorizzati nella cache per minuto, confrontandolo con il limite ITPM attuale. Accanto mostra il cache rate, così puoi monitorare l'avvicinamento a un limite prima di raggiungerlo in produzione.

Per leggere i limiti configurati tramite codice:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

È necessaria una chiave API Admin. GET /v1/organizations/workspaces/{workspace_id}/rate_limits esegue la stessa operazione per un workspace. Entrambe le operazioni sono di sola lettura. Per modificare un limite, usa la scheda Limits nella Console.

Usare meno, per rientrare più facilmente nei limiti

In entrambi i sistemi, alla base viene conteggiata la stessa unità, quindi queste impostazioni funzionano su entrambi.

• Usa meno token per turno. Le sessioni continue mantengono la cache disponibile e /clear tra attività non correlate non comporta costi. L'uso dei token in Claude Code descrive tutte queste impostazioni in dettaglio.
• Riduci il livello di elaborazione. I livelli sono low, medium, high, xhigh e max. Il menu /effort offre anche ultracode, che aumenta il consumo invece di ridurlo. Un ragionamento approfondito non serve per una ridenominazione meccanica.
• Riduci la concorrenza dopo un errore 429. Abbassa CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY ed evita di eseguire molti subagent in parallelo. Esegui anche /status: un ANTHROPIC_API_KEY residuo instrada le richieste tramite una chiave di livello inferiore invece che tramite il tuo abbonamento.
• Sposta il lavoro non interattivo nella Message Batches API. Esegue grandi volumi in modo asincrono, con uno sconto del 50% sui token di input e output e limiti di frequenza propri. In questo modo un job notturno non compete con la sessione.

Questo problema è più evidente per le attività che riversano molti dati nel contesto: se stai analizzando azioni e opzioni con dati di mercato in tempo reale, estrarre solo la porzione necessaria per ogni domanda costa una frazione rispetto a incollare intere tabelle di quotazioni e catene di opzioni. Il lavoro a raffiche gestito da un programma, anziché da una persona, dovrebbe usare fin dall'inizio una chiave API. Il passaggio cambia sia il metodo di pagamento sia il modo in cui vengono applicati i limiti, perché Claude API non offre un piano gratuito oltre al piccolo credito assegnato alla registrazione. La tua prima app Claude API su un VPS descrive la gestione delle chiavi e dei tentativi, mentre un'esecuzione lunga dell'agente può continuare dopo una perdita di connessione se mantieni Claude Code in esecuzione su un VPS all'interno di tmux.

FAQ

Perché cambiare modello non risolve il limite di utilizzo di Claude?

Perché i limiti della sessione e quelli settimanali sono condivisi da tutti i modelli. La quota dipende dal piano, non dal modello: /model cambia il modello che risponderebbe, ma non la quota residua. L'unica eccezione è You've hit your Opus limit, che si applica solo alle richieste a Opus. In questo caso, cambiare modello è la soluzione documentata.

Che cosa significa l'errore 429 rate_limit_error e quanto devo aspettare?

Indica che l'account ha raggiunto un limite di frequenza per quella classe di modelli: richieste al minuto, token di input al minuto oppure token di output al minuto. La risposta contiene un'intestazione retry-after con il numero di secondi da attendere; i tentativi anticipati falliscono. Gli SDK ufficiali eseguono già nuovi tentativi per i limiti di frequenza e per gli errori 5xx, usando per impostazione predefinita un backoff esponenziale per 2 tentativi e rispettando quell'intestazione. Un errore 429 che arriva mentre si è ancora entro i limiti del proprio tier indica un limite di accelerazione dovuto a un aumento improvviso del ritmo delle richieste.

Come posso visualizzare i limiti di utilizzo di Claude e sapere quando vengono reimpostati?

In Claude Code, esegui /usage per visualizzare le barre relative al piano, gli orari di reimpostazione e una suddivisione dell'utilizzo; /cost è un alias, mentre d o w permette di passare dalle ultime 24 ore agli ultimi 7 giorni e viceversa. Questi dati provengono dalla cronologia locale delle sessioni, quindi non includono l'utilizzo da altri dispositivi né quello effettuato tramite claude.ai. Per l'API, la Console mostra i grafici dei limiti di frequenza e GET /v1/organizations/rate_limits restituisce i limiti configurati usando una chiave Admin API.

Posso continuare a lavorare dopo aver raggiunto il limite del mio piano Claude?

A volte. Esegui /usage-credits per acquistare ulteriore utilizzo oltre il limite su Pro e Max, oppure per richiederlo a un amministratore su Team ed Enterprise; è necessario accedere a claude.ai tramite /login e questa funzione non è disponibile con l'autenticazione tramite chiave API. In alternativa, attendi l'orario di reimpostazione, cambia modello se hai raggiunto il limite di Opus oppure sposta il lavoro su una chiave API, che applica i limiti al minuto anziché per finestra temporale.