Limiti di velocità

Esistono due tipi di limiti:

1. I limiti di spesa stabiliscono un costo mensile massimo che un'organizzazione può sostenere per l'utilizzo dell'API.
2. I "rate limits" (limiti di velocità) stabiliscono il numero massimo di richieste API che un'organizzazione può effettuare in un determinato periodo di tempo.

L'API applica limiti configurati dal servizio a livello di organizzazione, ma puoi anche impostare limiti configurabili dall'utente per i workspace della tua organizzazione.

Informazioni sui limiti di velocità

• I limiti sono progettati per prevenire l'abuso dell'API, riducendo al minimo l'impatto sui modelli di utilizzo più comuni dei clienti.
• I limiti sono definiti in base al livello di utilizzo ("usage tier"). Le organizzazioni vengono collocate automaticamente in un livello in base alla cronologia di utilizzo e allo stato dell'account, e possono passare a un livello superiore nel tempo man mano che utilizzano l'API.
• Le nuove organizzazioni e le organizzazioni con una cronologia di utilizzo limitata possono iniziare nel livello Evaluation, con limiti inferiori ai limiti standard mostrati in questa pagina mentre viene costruita la cronologia dell'account. Questi limiti iniziali fanno parte del modo in cui Anthropic previene frodi e abusi, e aumentano automaticamente man mano che la tua organizzazione accumula cronologia di utilizzo.
• I limiti sono impostati a livello di organizzazione. Puoi vedere il livello e i limiti attuali della tua organizzazione nella pagina Limiti di velocità della Claude Console.
• Potresti raggiungere i limiti di velocità su intervalli di tempo più brevi. Ad esempio, una velocità di 60 richieste al minuto (RPM) potrebbe essere applicata come 1 richiesta al secondo. Brevi raffiche di richieste possono superare il limite e generare errori di limite di velocità.
• I limiti seguenti sono i limiti standard per ciascun livello. Se hai bisogno di limiti più elevati, consulta Richiedere limiti più elevati.
• L'API utilizza l'algoritmo token bucket per applicare i limiti di velocità. Ciò significa che la tua capacità viene continuamente ripristinata fino al limite massimo, anziché essere azzerata a intervalli fissi.
• Tutti i limiti qui descritti rappresentano l'utilizzo massimo consentito, non minimi garantiti. Questi limiti hanno lo scopo di ridurre le spese eccessive involontarie e garantire una distribuzione equa delle risorse tra gli utenti.

Limiti di spesa

Ciascuno dei livelli Start, Build e Scale prevede un tetto di spesa mensile, ovvero l'importo massimo che la tua organizzazione può spendere per l'API in ogni mese solare. Puoi visualizzare il tetto di spesa mensile della tua organizzazione e impostare un tuo limite nella pagina Fatturazione.

Le organizzazioni nel livello Custom non hanno un tetto di spesa mensile; i limiti vengono concordati con il loro team di account.

Raggiungimento del tetto di spesa

Una volta raggiunto il tetto di spesa del tuo livello, l'utilizzo dell'API viene sospeso fino alle 00:00 UTC del primo giorno del mese successivo, a meno che tu non richieda prima un limite più elevato. Mentre l'utilizzo è sospeso, le richieste API restituiscono HTTP 429:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "You have reached your API usage limits: your organization has crossed its monthly API usage threshold, set based on your organization's API tier. You will regain access on 2026-09-01 at 00:00 UTC.",
    "details": { "error_code": "enforced_spend_limit_reached" }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

• Il tipo di errore è rate_limit_error, lo stesso di un limite di velocità, ma la risposta non ha l'header retry-after. I nuovi tentativi, inclusi quelli automatici degli SDK, falliscono finché l'accesso non viene ripristinato.
• Nella Messages API, error.details.error_code è enforced_spend_limit_reached. Usalo per distinguere questa risposta da un limite di velocità.
• Il passaggio a un livello superiore ripristina l'accesso; consulta Richiedere limiti più elevati.

Impostare un proprio limite di spesa

Puoi anche impostare un tuo limite di spesa inferiore al tetto del tuo livello per controllare i costi:

1. 1

   Vai alla pagina Fatturazione

   Vai a Settings > Billing nella Claude Console.

2. 2

   Apri l'editor del limite di spesa

   Nella sezione Spend limits, fai clic su Adjust limit (o Set limit se non è attualmente impostato alcun limite).

3. 3

   Modifica il tuo limite di spesa

   Inserisci un nuovo valore. Il tuo limite di spesa non può superare il tetto del tuo livello attuale.

Quando l'utilizzo raggiunge un limite di spesa da te impostato, le richieste restituiscono HTTP 400 con tipo di errore invalid_request_error. Il messaggio inizia con You have reached your specified API usage limits, oppure You have reached your specified workspace API usage limits per un limite di workspace, e indica quando l'accesso verrà ripristinato. Aumenta o rimuovi il limite per ripristinare l'accesso prima.

I limiti sul workspace Claude Code vengono verificati separatamente: le richieste di Claude Code che superano il limite di quel workspace possono invece ricevere un 429 che include un header retry-after.

Limiti di velocità

I limiti di velocità per la Messages API sono misurati in richieste al minuto (RPM), token di input al minuto (ITPM) e token di output al minuto (OTPM) per ciascuna classe di modello. Se superi uno qualsiasi dei limiti di velocità riceverai un errore 429 che descrive quale limite di velocità è stato superato, insieme a un header retry-after che indica quanto tempo attendere.

ITPM sensibile alla cache

Molti fornitori di API utilizzano un limite combinato di "token al minuto" (TPM) che può includere tutti i token, sia in cache che non in cache, di input e di output. Per la maggior parte dei modelli Claude, solo i token di input non in cache vengono conteggiati ai fini dei limiti di velocità ITPM. Questo è un vantaggio fondamentale che rende i limiti di velocità effettivamente più elevati di quanto potrebbero sembrare inizialmente.

I limiti di velocità ITPM vengono stimati all'inizio di ogni richiesta e la stima viene corretta durante la richiesta per riflettere il numero effettivo di token di input utilizzati.

Ecco cosa viene conteggiato ai fini dell'ITPM:

• input_tokens (token dopo l'ultimo breakpoint di cache) ✓ Conteggiati ai fini dell'ITPM
• cache_creation_input_tokens (token in fase di scrittura nella cache) ✓ Conteggiati ai fini dell'ITPM
• cache_read_input_tokens (token letti dalla cache) ✗ NON conteggiati ai fini dell'ITPM per la maggior parte dei modelli

Esempio: Con un limite ITPM di 2.000.000 e un tasso di cache hit dell'80%, potresti elaborare effettivamente 10.000.000 di token di input totali al minuto (2M non in cache + 8M in cache), perché i token in cache non vengono conteggiati nel tuo limite di velocità.

Per sfruttare al meglio i tuoi limiti di velocità, metti in cache i contenuti ripetuti come istruzioni di sistema e prompt, documenti di contesto di grandi dimensioni, definizioni di strumenti e cronologia delle conversazioni; consulta la cache dei prompt per indicazioni. Con una cache efficace, puoi aumentare sostanzialmente il tuo throughput effettivo senza aumentare i limiti di velocità. Monitora il tuo tasso di cache hit nella pagina Utilizzo per ottimizzare la tua strategia di cache.

I limiti di velocità OTPM vengono valutati in tempo reale man mano che i token di output vengono prodotti, conteggiando solo i token effettivamente generati. Il parametro max_tokens non rientra nel calcolo dei limiti di velocità OTPM, quindi non vi è alcuno svantaggio in termini di limiti di velocità nell'impostare un valore max_tokens più elevato.

I limiti di velocità vengono applicati separatamente per ciascun modello; pertanto puoi utilizzare modelli diversi fino ai rispettivi limiti contemporaneamente. Puoi verificare i tuoi limiti di velocità attuali e il relativo comportamento nella pagina Limiti di velocità della Claude Console, oppure leggere i limiti configurati in modo programmatico con la Rate Limits API.

^{1 Il limite di velocità Fable è un limite totale che si applica al traffico combinato di Claude Fable 5.1 e Claude Fable 5. Claude Mythos 5.1 e Claude Mythos 5 condividono un limite combinato separato alle stesse condizioni.}

^{2 Il limite di velocità di Opus è un limite totale che si applica al traffico combinato di Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5. Claude Opus 5.5 e Claude Opus 5 hanno ciascuno un limite di velocità separato e non fanno parte di questo bucket combinato.}

^{3 Il limite di velocità di Sonnet 4.x è un limite totale che si applica al traffico combinato di Sonnet 4.6 e Sonnet 4.5. Claude Sonnet 5.5 e Claude Sonnet 5 hanno ciascuno un limite di velocità separato e non fanno parte di questo bucket combinato.}

^{4 Il limite conteggia cache_read_input_tokens ai fini dell'utilizzo ITPM.}

Message Batches API

La Message Batches API ha un proprio insieme di limiti di velocità condivisi tra tutti i modelli. Questi includono un limite di richieste al minuto (RPM) per tutti gli endpoint dell'API e un limite al numero di richieste batch che possono trovarsi contemporaneamente nella coda di elaborazione. Per "richiesta batch" si intende qui una parte di un Message Batch. Puoi creare un Message Batch contenente migliaia di richieste batch, ciascuna delle quali viene conteggiata ai fini di questo limite. Una richiesta batch è considerata parte della coda di elaborazione quando non è ancora stata elaborata con successo dal modello.

Managed Agents

Gli endpoint di Claude Managed Agents sono soggetti a limiti di velocità per organizzazione. Questi limiti sono separati dai limiti di velocità della Messages API indicati sopra.

Files API

Le richieste alla Files API hanno un proprio limite per organizzazione, condiviso tra le operazioni di caricamento, elenco, recupero, download ed eliminazione e separato dai limiti della Messages API descritti in precedenza in questa pagina. Consulta Limiti di velocità della Files API per il valore attuale.

Limiti di velocità della modalità veloce

Quando utilizzi la modalità veloce (anteprima di ricerca) con speed: "fast" su Claude Opus 5.5, Claude Opus 5, o Opus 4.8, si applicano limiti di velocità dedicati, separati dai limiti di velocità standard di Opus. Quando i limiti di velocità della modalità veloce vengono superati, l'API restituisce un errore 429 con un header retry-after. La modalità veloce non è disponibile su Claude Opus 4.7 (le richieste restituiscono un errore) né su Claude Opus 4.6 (le richieste a claude-opus-4-6 con speed: "fast" vengono eseguite a velocità standard). Consulta Modalità veloce.

La risposta include header anthropic-fast-* che indicano lo stato dei tuoi limiti di velocità della modalità veloce. Consulta Limiti di velocità della modalità veloce per i dettagli su questi header.

Monitorare i limiti di velocità nella Console

Puoi monitorare l'utilizzo dei tuoi limiti di velocità nella pagina Utilizzo della Claude Console.

Oltre a fornire grafici di token e richieste, la pagina Utilizzo fornisce due grafici separati sui limiti di velocità. Usa questi grafici per vedere quanto margine di crescita hai, identificare quando potresti raggiungere i picchi di utilizzo, capire quali limiti di velocità richiedere e scoprire come migliorare i tuoi tassi di cache. I grafici visualizzano una serie di metriche per un determinato limite di velocità (ad esempio, per modello):

• Il grafico Rate Limit - Input Tokens include:
  • Il massimo orario di token di input non in cache al minuto
  • Il tuo attuale limite di velocità di token di input al minuto
  • Il tasso di cache per i tuoi token di input (ovvero la percentuale di token di input letti dalla cache)
• Il grafico Rate Limit - Output Tokens include:
  • Il massimo orario di token di output al minuto
  • Il tuo attuale limite di velocità di token di output al minuto

Richiedere limiti più elevati

Per richiedere limiti di velocità più elevati o un tetto di spesa mensile più alto, usa Request rate limit increase nella pagina Limiti di velocità. Anche il supporto Anthropic può aumentare i limiti; per esigenze urgenti, contatta il supporto Anthropic.

Impostare limiti inferiori per i Workspace

Per maggiori informazioni sui workspace, consulta Workspace.

Per proteggere i Workspace della tua Organizzazione da un potenziale utilizzo eccessivo, puoi impostare limiti di spesa e di velocità personalizzati per ciascun Workspace.

Esempio: se il limite della tua Organizzazione è di 40.000 token di input al minuto e 8.000 token di output al minuto, potresti limitare un Workspace a 30.000 token di input al minuto. Questo protegge gli altri Workspace da un potenziale utilizzo eccessivo e garantisce una distribuzione più equa delle risorse all'interno della tua Organizzazione. I restanti token al minuto non utilizzati (o di più, se quel Workspace non utilizza tutto il limite) sono quindi disponibili per gli altri Workspace.

Nota:

• Non puoi impostare limiti sul Workspace predefinito.
• Se non impostati, i limiti del Workspace corrispondono al limite dell'Organizzazione.
• I limiti del Workspace vengono impostati per tipo di limitatore (ad esempio richieste al minuto, token di input al minuto o token di output al minuto).
• I limiti a livello di Organizzazione si applicano sempre, anche se la somma dei limiti dei Workspace è superiore.

Per leggere in modo programmatico i limiti di velocità attuali della tua organizzazione e dei tuoi workspace, usa la Rate Limits API.

Header di risposta

La risposta dell'API include header che mostrano il limite di velocità applicato, l'utilizzo attuale e quando il limite verrà ripristinato.

Vengono restituiti i seguenti header:

Gli header anthropic-ratelimit-tokens-* mostrano i valori del limite più restrittivo attualmente in vigore. Ad esempio, se hai superato il limite di token al minuto del Workspace, gli header conterranno i valori del limite di velocità di token al minuto del Workspace. Se i limiti del Workspace non si applicano, gli header restituiranno i token totali rimanenti, dove il totale è la somma dei token di input e di output. Questo approccio garantisce visibilità sul vincolo più rilevante per il tuo attuale utilizzo dell'API. Per vedere su quale Workspace è stata conteggiata una richiesta, leggi l'header di risposta anthropic-workspace-id, che contiene l'ID del Workspace a cui la tua chiave API o il tuo token di accesso è stato risolto.