Limiti di frequenza e quote

Due tipi di limiti mantengono l’API veloce per tutti:

• Il limite di frequenza di una chiave: quante richieste al secondo può inviare, con un burst per i picchi brevi.
• Le quote dell’organizzazione: quante richieste possono inviare tutte le sue chiavi insieme al minuto, al giorno e al mese.

Entrambi dipendono dal piano dell’organizzazione. Ogni risposta ti dice a che punto sei, quindi un client ben fatto non deve mai tirare a indovinare.

Limite di frequenza di una chiave

Ogni chiave riceve una frequenza costante e un burst. Il burst ti permette di inviare quel numero di richieste tutte insieme; dopo, le richieste sono consentite alla frequenza costante.

La classe dipende dal piano dell’organizzazione. GET /v1/me mostra la classe, la frequenza e il burst della chiave che lo chiama (rate_limit). Il limite vale per la chiave nel suo insieme, qualunque sia il numero di server dell’API che servono le tue richieste.

Gli endpoint in streaming, POST /v1/chat (con o senza "stream": true) e GET /v1/jobs/stream, sono esclusi dal limite di frequenza della chiave: non lo consumano e le loro intestazioni RateLimit non hanno l’elemento "key". Contano invece per le quote dell’organizzazione, una volta ciascuno, quando la richiesta inizia. Le domande hanno limiti propri, descritti più avanti.

Quote dell’organizzazione

Un piano può impostare quote di richieste per l’organizzazione: al minuto, al giorno e al mese. Le finestre sono periodi di calendario in UTC: un minuto inizia a :00 secondi, un giorno alle 00:00 UTC, un mese il primo giorno alle 00:00 UTC. Conta ogni richiesta con una chiave o un token OAuth dell’organizzazione, su qualsiasi indirizzo. Una richiesta in streaming conta una volta, quando inizia, per quanto duri; con una quota esaurita viene rifiutata con 429 come qualsiasi altra richiesta. Una richiesta rifiutata con 429 non conta.

Le intestazioni

Ogni risposta a una richiesta con una chiave porta i limiti che le si applicano:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy e RateLimit seguono la bozza IETF RateLimit header fields for HTTP. Ogni elemento è un limite:

X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset riportano il più severo di questi limiti in una forma più semplice, per i client scritti prima che esistesse RateLimit. X-RateLimit-Reset è in secondi.

Quando si raggiunge un limite

L’API risponde 429 Too Many Requests con un’intestazione Retry-After in secondi:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Attendi il tempo indicato da Retry-After e ripeti la richiesta. Ripeti POST e PATCH con la stessa Idempotency-Key. Le funzioni di supporto per i nuovi tentativi in Errori fanno entrambe le cose.

Anche altri limiti del piano rispondono 429 con Retry-After, per esempio il numero di domande al giorno (limits.questions) o le risposte in corso nello stesso momento (limits.concurrent_answers). Gestiscili allo stesso modo.

Restare entro i limiti

• Leggi RateLimit e rallenta quando r si abbassa, invece di aspettare un 429.
• Distribuisci nel tempo il lavoro massivo e usa gli endpoint batch dove esistono: un batch di 100 documenti è una sola richiesta.
• Non controllare le modifiche con un ciclo serrato. Sottoscrivi i webhook, oppure leggi il feed degli eventi ogni pochi secondi.
• Esegui i worker in parallelo con un limitatore condiviso. Più processi con una sola chiave condividono un solo limite di frequenza.
• Chiedi al tuo referente in Sursa una classe più alta se la tua integrazione ne ha bisogno.