Errori "Rate limit reached" di OpenAI: cosa significano e come gestirli

L'API OpenAI restituisce 429 con "Rate limit reached" quando l'organizzazione ha inviato più richieste o più token al minuto rispetto ai limiti consentiti. I limiti si applicano all'organizzazione, non a ogni utente. Questi errori sono temporanei. Se si attende e si invia nuovamente la richiesta, in genere ha esito positivo. Alcuni altri 429 errori di OpenAI riguardano la fatturazione e quelli non vanno via quando si attende. Per altre informazioni, vedere Codici di errore.

Che aspetto hanno gli errori di limite di frequenza di OpenAI

La maggior parte di questi errori condivide lo 429 stato, quindi non è possibile distinguerli in base al solo stato. Leggere error.code nel corpo della risposta.

Come gestire gli errori di limite di frequenza di OpenAI

1. Controlla error.code per prima cosa. Se si tratta di un codice di fatturazione come credit_balance_exhausted, interrompere i tentativi e informare l'utente. Riprovare dopo un errore di fatturazione non ripristinerà l'accesso.
2. Segui Retry-After quando è presente. Se manca, usare il backoff esponenziale con il jitter e limitare il numero di tentativi.
3. Rallentare dopo slow_down. Ridurre la frequenza delle richieste, quindi aumentarla gradualmente. La regola pratica di OpenAI per valori superiori a 1M TPM di input consiste nell'aumentare il traffico di non più del 50% ogni 15 minuti.
4. Inviare meno token dopo un errore TPM. Prompt e risposte più brevi consentono di adattare più richieste in ogni minuto.
5. Arretrare ulteriormente dopo un 503. Aumentare il ritardo tra i tentativi e controllare la pagina di stato OpenAI.
6. Dire all'utente cosa sta succedendo. "Operazione in corso, riprovare tra 5 secondi" batte uno spinner che non termina mai.

OpenAI Python SDK ritenta in caso di errori di connessione e di risposte 408, 409, 429 e 5xx 2 volte per impostazione predefinita, con un breve backoff esponenziale. È possibile modificarlo con max_retries. Quando si esauriscono i tentativi, l'SDK genera RateLimitError per un InternalServerError e 429 per un 503, quindi il codice necessita ancora di un piano:

import openai
from openai import OpenAI

client = OpenAI(max_retries=3)

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}


def summarize(text: str) -> str | None:
    try:
        response = client.responses.create(model="gpt-4.1", input=text)
        return response.output_text
    except openai.RateLimitError as error:
        if error.code in BILLING_CODES:
            raise  # Retrying won't help: alert and tell the user
        return None  # Still throttled after retries: show "busy, try again"
    except openai.InternalServerError:
        return None

Come testare che l'app gestisca i rate limit di OpenAI

Raramente si raggiunge un limite di frequenza OpenAI durante lo sviluppo. Sei l'unico utente e le tue richieste sono brevi. Quindi, il modo in cui si testa la gestione dei limiti di frequenza decide se si trovano i bug prima che lo facciano i tuoi utenti.

Provalo nella tua app

Dev Proxy intercetta le richieste dell'app a api.openai.com e restituisce errori OpenAI, mentre l'app continua a chiamare gli URL reali. Il openai-throttling set di impostazioni ha esito negativo per la maggior parte delle richieste con una selezione casuale da TPM e RPM rate_limit_exceeded, slow_down, credit_balance_exhausted, e 503server_is_overloaded errori, nel formato di OpenAI. Le risposte relative al limite di frequenza 429 includono un'intestazione Retry-After e, se l'app ritenta prima che sia trascorso quel tempo, Dev Proxy lo segnala.

Scaricare il set di impostazioni e avviare Dev Proxy con esso:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Eseguire quindi l'app come di consueto e osservare cosa fa. Per installare Dev Proxy, vedere Configurare Dev Proxy.

Per testare il comportamento dell'app quando esaurisce i token al minuto, in base al prompt e ai token di completamento usati dalle richieste, vedere Testare i limiti dei token del modello linguistico.

Passaggi successivi

Vedere anche

• OpenAI insufficient_quota e credit_balance_exhausted: perché la ripetizione dei tentativi non è utile
• 429 Troppe richieste: cosa significa e come gestirlo
• Intestazione Retry-After: tempo di attesa prima di riprovare
• Simula gli errori delle API OpenAI
• LanguageModelRateLimitingPlugin