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

Status Error Che cosa significa Riprova?
429 rate_limit_exceeded, richieste al minuto (RPM) Sono state inviate troppe richieste in un minuto. Sì, dopo Retry-After
429 rate_limit_exceeded, token al minuto (TPM) Le richieste hanno usato troppi token in un minuto. Il messaggio mostra il limite, il numero di token usati e quanti token sono stati richiesti dalla richiesta. Sì, dopo Retry-After. Le richieste più brevi aiutano.
429 slow_down (tipo rate_limit_error) Il tuo traffico è cresciuto troppo rapidamente, anche se sei entro i limiti RPM e TPM. Sì, a un tasso inferiore
503 server_is_overloaded (tipo service_unavailable_error) I server OpenAI sono occupati. Sì, con ritardi più lunghi ogni volta
429 credit_balance_exhausted, limite di spesa o errori di limite di utilizzo (tipo insufficient_quota) Hai esaurito i crediti o hai superato un limite. No. Vedi OpenAI insufficient_quota e credit_balance_exhausted.

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.

Avvicinarsi Cosa trovi Quello che ti manca
Attendere l'ambiente di produzione Guasti reali Tutto, fino a quando un utente non ci fa clic
Simula l'API nei test oppure consenti all'agente di coding di scrivere il mock Se il ramo di ripetizione dei tentativi viene eseguito Corpi delle risposte di errore reali e codici di errore di OpenAI, e la politica di retry dell'SDK. L'app richiede anche un interruttore di sola prova per raggiungere il mock.
Chiama l'API reale finché non ti applica il rate limiting Comportamento reale Non è possibile attivare un errore specifico su richiesta e ogni richiesta costa token
Intercettare il traffico reale dell'app e restituire errori OpenAI su richiesta URL reali, l'SDK reale e la politica di retry, e il formato di errore di OpenAI Niente nella tua app cambia, quindi non testa il codice in isolamento. Mantieni gli unit test per quello.

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

Testare il modo in cui l'app gestisce i limiti di frequenza OpenAI

Vedere anche

  • Last updated on