Limiti di frequenza dell'API OpenAI — quale limite raggiungi, come leggerlo e il retry che lo risolve

Un 429 di OpenAI significa che hai superato uno dei cinque limiti — e il primo compito è capire quale, perché le soluzioni puntano in direzioni opposte. Questa pagina spiega cosa misura ciascun limite, come leggere la risposta direttamente dagli header, la logica di retry che ferma davvero gli errori e cosa fare quando un backoff corretto non basta.

Verificato il 30 settembre 2026 sulla base della documentazione sui limiti di frequenza di OpenAI.

Cinque limiti, ognuno dei quali può attivarsi

Il primo limite a esaurirsi attiva l’errore, quindi “siamo ben lontani dal limite dei token” non è un motivo per escludere un limite di frequenza — potresti essere lontano dal TPM e avere raggiunto esattamente l’RPM. I limiti si applicano per organizzazione e per modello, non per chiave: creare chiavi aggiuntive non crea quota aggiuntiva.

Come appare un 429

HTTP/1.1 429 Too Many Requests
retry-after: 12
x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 12s
x-ratelimit-limit-tokens: 200000
x-ratelimit-remaining-tokens: 143820
x-ratelimit-reset-tokens: 17s

{
  "error": {
    "message": "Rate limit reached for gpt-5.4 in organization org-... on requests per min (RPM).",
    "type": "requests",
    "code": "rate_limit_exceeded"
  }
}

Tutto ciò che ti serve è in quella risposta. Il corpo indica la dimensione (“requests per min (RPM)”) e gli header forniscono il limite esatto, ciò che resta e quando viene ripristinato.

Tier di utilizzo

I tuoi limiti sono determinati dal tier di utilizzo, che OpenAI aumenta automaticamente all’accumularsi della spesa cumulativa:

Qui non riportiamo volutamente i numeri RPM e TPM per modello. Differiscono da un modello all’altro, cambiano quando vengono rilasciati nuovi modelli e possono essere modificati per account — quindi qualsiasi tabella pubblicata su una pagina di terze parti è una stima con una data. Le due fonti autorevoli per il tuo account sono la pagina dei limiti nella dashboard di OpenAI e gli header x-ratelimit-* di ogni risposta che già effettui. Leggi gli header.

La soluzione: rispettare Retry-After, poi aggiungere jitter

La raccomandazione documentata da OpenAI è l’exponential backoff con jitter, seguendo Retry-After quando la risposta lo include. Entrambe le parti sono importanti. Senza l’header potresti riprovare troppo presto; senza jitter, ogni client che ha fallito nello stesso istante riprova nello stesso istante e fallisce insieme — un thundering herd che trasforma un secondo negativo in un minuto negativo.

import random, time
import openai

client = openai.OpenAI()

def call_with_backoff(fn, *, max_attempts=6, base=0.5, cap=30.0):
    """Retry 429s: honour Retry-After when present, jittered backoff otherwise."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except openai.RateLimitError as err:
            if attempt == max_attempts - 1:
                raise
            # The server's own answer beats any formula you invent.
            retry_after = (err.response.headers or {}).get("retry-after")
            if retry_after:
                delay = float(retry_after)
            else:
                # Full jitter: sleep a random point in [0, 2^n * base], capped.
                # Without the randomness every client that failed at the same
                # instant retries at the same instant and fails again together.
                delay = random.uniform(0, min(cap, base * 2**attempt))
            time.sleep(delay)

resp = call_with_backoff(lambda: client.responses.create(
    model="gpt-5.4",
    input="Summarise this changelog in three bullets.",
))

La stessa logica in TypeScript:

import OpenAI from "openai";

const client = new OpenAI();
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function callWithBackoff<T>(
  fn: () => Promise<T>,
  { maxAttempts = 6, baseMs = 500, capMs = 30_000 } = {},
): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = (err as { status?: number }).status;
      if (status !== 429 || attempt === maxAttempts - 1) throw err;

      const retryAfter = (err as { headers?: Headers }).headers?.get("retry-after");
      const delay = retryAfter
        ? Number(retryAfter) * 1000
        : Math.random() * Math.min(capMs, baseMs * 2 ** attempt);
      await sleep(delay);
    }
  }
}

const resp = await callWithBackoff(() =>
  client.responses.create({ model: "gpt-5.4", input: "Hello" }),
);

Gli SDK ufficiali effettuano già automaticamente i retry dei 429, quindi la maggior parte delle applicazioni ne ha bisogno solo quando avvolge le chiamate nel proprio client HTTP o quando desidera un comportamento diverso — un limite più lungo per il lavoro in background oppure un fallimento immediato per una richiesta rivolta all’utente, quando attendere 12 secondi è peggio di un errore.

Monitora prima che si rompa

I contatori sono presenti in ogni risposta, non solo negli errori. Registrare i valori rimanenti trasforma il rate limiting da incidente a indicatore — puoi vedere il margine ridursi giorni prima che un lancio lo esaurisca.

# Log the remaining counters on every response, not just on failures.
# By the time you see a 429 the useful signal is already an hour old.
resp = client.responses.with_raw_response.create(model="gpt-5.4", input="…")
h = resp.headers

log.info(
    "openai_quota model=%s req_left=%s tok_left=%s reset_req=%s reset_tok=%s",
    "gpt-5.4",
    h.get("x-ratelimit-remaining-requests"),
    h.get("x-ratelimit-remaining-tokens"),
    h.get("x-ratelimit-reset-requests"),
    h.get("x-ratelimit-reset-tokens"),
)

parsed = resp.parse()   # the normal response object

Due abitudini utili da adottare insieme: avvisa quando x-ratelimit-remaining-tokens scende sotto una certa frazione del limite, invece di basarti sul conteggio dei 429, e aggiungi jitter agli orari, non solo ai retry. Un cron che avvia tutto alle :00 crea da solo il proprio picco.

Quando il backoff non è la soluzione

Un backoff corretto risolve i picchi. Non fa nulla per una domanda sostenuta superiore al tuo limite — in quel caso i retry spostano soltanto il fallimento più avanti. Le soluzioni strutturali, in ordine approssimativo di impegno:

• Limita l’output. I token di ragionamento vengono addebitati e conteggiati come output, quindi una generazione senza limiti è il modo più rapido per consumare il TPM.
• Riduci il contesto recuperato. Con un limite TPM, dimezzare i chunk recuperati raddoppia il throughput gratuitamente.
• Scegli un modello adeguato. Un passaggio di classificazione non richiede un modello frontier e i modelli piccoli hanno un budget separato.
• Separa i carichi di lavoro. I job batch e il traffico sensibile alla latenza che competono per un unico limite a livello di organizzazione sono la causa più comune di questo problema autoindotto.
• Aumenta il tier. I tier aumentano con la spesa cumulativa, quindi spesso questo sta già avvenendo.

Distribuire il carico tra famiglie di modelli

L’ultimo punto dell’elenco è il motivo per cui un gateway è utile. Kunavo espone un’API compatibile con OpenAI — stesso SDK, stesso formato di chiamata, una chiave — attraverso diverse famiglie di modelli, quindi spostare un carico da un limite saturo richiede cambiare il nome del modello, non creare una seconda integrazione:

from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Same SDK, same call shape — the model string chooses the family.
client.chat.completions.create(
    model="gpt-5-6-terra",            # or claude-sonnet-5, claude-haiku-4-5, …
    messages=[{"role": "user", "content": "Hello"}],
)

In concreto: il job batch di riepilogo che competeva con il traffico di produzione può essere eseguito su claude-haiku-4-5 a $0,70 / $3,50 per 1M, mentre il percorso sensibile alla latenza resta su gpt-5-6-terra ($0,70 / $4,20) o claude-sonnet-5 ($1,40 / $7,00). Famiglia diversa, coda diversa.

Sii chiaro su ciò che questa soluzione fa e non fa. Rimuove il collo di bottiglia di un singolo account e singolo modello e offre un’alternativa verso cui effettuare il failover. Non crea capacità: se il volume totale supera realmente ciò che consente un singolo tier, la risposta resta aumentare il tier o fare meno lavoro. Le tariffe di ogni modello sono nella pagina dei prezzi e la guida equivalente per i limiti di Anthropic è in Claude API 429 rate_limit_error.

Domande frequenti