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 limiti di velocità stabiliscono il numero massimo di richieste API che un'organizzazione può effettuare in un periodo di tempo definito.

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 comuni dei clienti.
• I limiti sono definiti per livello di utilizzo. La tua organizzazione viene collocata automaticamente in un livello e può passare a un livello superiore nel tempo man mano che utilizzi l'API.
• I limiti sono impostati a livello di organizzazione. Puoi vedere il livello della tua organizzazione e i limiti attuali nella pagina Limits della Claude Console.
• Potresti raggiungere i limiti di velocità su intervalli di tempo più brevi. Ad esempio, un limite di 60 richieste al minuto (RPM) potrebbe essere applicato come 1 richiesta al secondo. Brevi picchi di richieste possono superare il limite e attivare errori di limite di velocità.
• I seguenti limiti 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 reimpostata a intervalli fissi.
• Tutti i limiti descritti qui rappresentano l'utilizzo massimo consentito, non minimi garantiti. Questi limiti hanno lo scopo di ridurre la spesa eccessiva involontaria e garantire un'equa distribuzione delle risorse tra gli utenti.



Limiti di spesa

Ciascuno dei livelli Start, Build e Scale prevede un tetto di spesa mensile, che è il massimo che la tua organizzazione può spendere per l'API ogni mese di calendario. Una volta raggiunto il tetto di spesa del tuo livello, l'utilizzo dell'API viene sospeso fino al mese successivo, a meno che tu non richieda un limite più elevato. Puoi visualizzare il tetto di spesa mensile della tua organizzazione nella pagina Limits.

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

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



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 consapevole della cache

Molti provider di API utilizzano un limite combinato di "token al minuto" (TPM) che può includere tutti i token, sia memorizzati nella cache che non, sia di input che di output. Per la maggior parte dei modelli Claude, solo i token di input non memorizzati nella cache contano ai fini dei tuoi limiti di velocità ITPM. Questo è un vantaggio chiave che rende i limiti di velocità effettivamente più elevati di quanto potrebbero inizialmente apparire.

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

Ecco cosa conta ai fini dell'ITPM:

• input_tokens (token dopo l'ultimo breakpoint della cache) ✓ Contano ai fini dell'ITPM
• cache_creation_input_tokens (token scritti nella cache) ✓ Contano ai fini dell'ITPM
• cache_read_input_tokens (token letti dalla cache) ✗ NON contano ai fini dell'ITPM per la maggior parte dei modelli

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

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

I limiti di velocità OTPM vengono valutati in tempo reale man mano che i token di output vengono prodotti, contando solo i token effettivamente generati. Il parametro max_tokens non influisce sui calcoli del limite di velocità OTPM, quindi non c'è alcuno svantaggio in termini di limite 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 simultaneamente. Puoi verificare i tuoi limiti di velocità attuali e il comportamento nella Claude Console, oppure leggere i limiti configurati a livello di programmazione con la Rate Limits API.

^{* - 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.}

^{** - 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 ha un limite di velocità separato e non fa parte di questo bucket combinato.}

^{† - Il limite conta cache_read_input_tokens ai fini dell'utilizzo ITPM.}



Message Batches API

La Message Batches API ha il proprio set di limiti di velocità che sono condivisi tra tutti i modelli. Questi includono un limite di richieste al minuto (RPM) per tutti gli endpoint API e un limite sul numero di richieste batch che possono essere nella coda di elaborazione contemporaneamente. Una "richiesta batch" qui si riferisce a una parte di un Message Batch. Puoi creare un Message Batch contenente migliaia di richieste batch, ognuna delle quali conta 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 hanno limiti di velocità per organizzazione. Questi limiti sono separati dai limiti di velocità della Messages API sopra indicati.



Limiti di velocità della fast mode

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

La risposta include header anthropic-fast-* che indicano lo stato del tuo limite di velocità della fast mode. Consulta Fast mode per i dettagli su questi header.



Monitoraggio dei tuoi limiti di velocità nella Console

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

Oltre a fornire grafici di token e richieste, la pagina Usage fornisce due grafici separati dei limiti di velocità. Usa questi grafici per vedere quanto margine hai per crescere, quando potresti raggiungere il picco di utilizzo, comprendere meglio quali limiti di velocità richiedere o come puoi migliorare i tuoi tassi di caching. I grafici visualizzano una serie di metriche per un determinato limite di velocità (ad esempio, per modello):

• Il grafico Rate Limit - Input Tokens include:
  • Massimo orario di token di input non memorizzati nella 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:
  • 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ù elevato, usa Request rate limit increase nella pagina Limits.



Impostare limiti inferiori per i Workspace

Per ulteriori informazioni sui workspace, consulta Workspace.

Per proteggere i Workspace nella tua Organizzazione da un potenziale utilizzo eccessivo, puoi impostare limiti di spesa e di velocità personalizzati per 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 nella tua Organizzazione. I restanti token al minuto non utilizzati (o più, se quel Workspace non utilizza il limite) sono quindi disponibili per l'uso da parte di 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 sono impostati per tipo di limitatore (come 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 i tuoi attuali limiti di velocità dell'organizzazione e del workspace a livello di programmazione, usa la Rate Limits API.



Header di risposta

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

Vengono restituiti i seguenti header:

Gli header anthropic-ratelimit-tokens-* mostrano i valori per il 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à dei 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 output. Questo approccio garantisce che tu abbia visibilità sul vincolo più rilevante per il tuo attuale utilizzo dell'API.