Limiti di velocità

Esistono due tipi di limiti:

1. I limiti di spesa impostano un costo mensile massimo che un'organizzazione può sostenere per l'utilizzo dell'API.
2. I limiti di velocità impostano 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 abusi dell'API, riducendo al minimo l'impatto sui modelli di utilizzo comuni dei clienti.
• I limiti sono definiti per 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 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 preveniamo frodi e abusi, e aumentano automaticamente man mano che la tua organizzazione costruisce una cronologia di utilizzo.
• I limiti sono impostati a livello di organizzazione. Puoi vedere il livello della tua organizzazione e i limiti attuali nella pagina Limits nella 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 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 reintegrata fino al tuo limite massimo, anziché essere azzerata a intervalli fissi.
• Tutti i limiti descritti qui rappresentano l'utilizzo massimo consentito, non minimi garantiti. Questi limiti sono intesi a ridurre le spese eccessive non intenzionali e a 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 sull'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 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 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 sembrare.

I limiti di velocità ITPM vengono stimati all'inizio di ogni richiesta, e la stima viene aggiustata 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 in fase di scrittura 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 in cache + 8M in cache), perché i token in 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 dei limiti 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 contemporaneamente. Puoi controllare i tuoi limiti di velocità attuali e il loro comportamento nella pagina Limits nella Claude Console, oppure leggere i limiti configurati in modo programmatico con la Rate Limits API.

^{* Il limite di velocità di Opus è un limite totale che si applica al traffico combinato tra Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5. Claude Opus 5 ha un limite di velocità separato e non fa parte di questo bucket combinato.}

^{** Il limite di velocità di Sonnet 4.x è un limite totale che si applica al traffico combinato tra 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 insieme 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 trovarsi contemporaneamente nella coda di elaborazione. 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 modalità veloce

Quando utilizzi la modalità veloce (anteprima di ricerca) con speed: "fast" su Claude Opus 5, 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 modalità veloce vengono superati, l'API restituisce un errore 429 con un header retry-after. La modalità veloce non è disponibile 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 del tuo limite di velocità della modalità veloce. Consulta Limiti di velocità della modalità veloce per i dettagli su questi header.



Monitorare i 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 quale margine di crescita hai, identificare quando potresti raggiungere il picco di utilizzo, capire quali limiti di velocità richiedere e imparare come 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 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:
  • 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 maggiori informazioni sui workspace, consulta Workspaces.

Per proteggere i Workspace nella 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 nella tua Organizzazione. I restanti token al minuto non utilizzati (o di più, se quel Workspace non utilizza il limite) sono quindi disponibili per l'uso da parte degli 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 in modo programmatico i limiti di velocità attuali della tua organizzazione e dei 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à azzerato.

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à dei token al minuto del Workspace. Se i limiti del Workspace non si applicano, gli header restituiranno il totale dei token rimanenti, dove il totale è la somma dei token di input e di output. Questo approccio garantisce che tu abbia visibilità sul vincolo più rilevante per il tuo attuale utilizzo dell'API.