Panoramica
L'utilizzo dell'API è soggetto a limiti di richieste. Questi limiti vincolano il numero di richieste, token o altri utilizzi in un determinato periodo.
Una risposta 429 può indicare un limite di richieste temporaneo, l'esaurimento del saldo prepagato oppure un limite di spesa o utilizzo. Controlla i dettagli dell'errore prima di riprovare o modificare le impostazioni di fatturazione.
Individua la causa
Leggi il messaggio di errore e, se fornito, error.code. Gli errori relativi alla fatturazione possono comunque usare il valore più generico insufficient_quota per error.type.
| Errore o codice | Significato | Cosa fare |
| Limite di richieste o token raggiunto | Le richieste superano un limite di richieste applicabile. | Distribuisci le richieste nel tempo e segui le indicazioni riportate di seguito per riprovare. |
| credit_balance_exhausted | L'organizzazione non dispone più di crediti prepagati. | Aggiungi crediti nelle impostazioni di fatturazione dell'API. |
| organization_usage_limit_exceeded | L'organizzazione ha raggiunto il limite di utilizzo assegnato da OpenAI. | Richiedi l'approvazione di un limite di utilizzo superiore. |
| organization_spend_limit_exceeded | L'organizzazione ha raggiunto il limite di spesa imposto. | Aumenta o rimuovi il limite oppure attendi il ripristino mensile. |
| project_spend_limit_exceeded | Il progetto ha raggiunto il limite di spesa imposto. | Aumenta o rimuovi il limite del progetto oppure attendi il ripristino mensile. |
Riprovare dopo un errore di fatturazione, spesa o quota non ripristina l'accesso. Risolvi prima il problema relativo al saldo o al limite indicato. L'applicazione delle modifiche ai limiti di spesa imposti può richiedere tempo.
Per modificare un limite di spesa è necessaria l'autorizzazione a gestire le impostazioni dell'organizzazione o del progetto interessato. Se non hai accesso, rivolgiti alla persona che gestisce queste impostazioni.
Per l'acquisto di crediti prepagati, consulta: Configurazione e gestione della fatturazione prepagata dell'API.
Per informazioni sui diversi controlli di spesa, consulta la guida ai limiti di spesa dell'API.
Controlla i limiti di richieste applicabili
Vai alla pagina Limiti dell'organizzazione per consultarne il livello di utilizzo e i limiti attuali.
I limiti di richieste possono essere applicati a livello di organizzazione e di progetto. Non sono quote assegnate ai singoli utenti. I limiti variano anche in base al modello e alcune famiglie di modelli condividono lo stesso limite.
Controlla quale limite è indicato nell'errore. Ad esempio, le richieste al minuto e i token al minuto sono soggetti a limiti distinti. Puoi raggiungere un limite pur rimanendo al di sotto dell'altro.
Verifica l'organizzazione usata dalla richiesta
Se appartieni a più organizzazioni, verifica che le richieste usino l'organizzazione e il progetto desiderati.
Se la tua chiave API usa un'organizzazione predefinita, controlla l'impostazione dell'organizzazione predefinita. Organizzazioni diverse possono avere modalità di fatturazione e livelli di utilizzo differenti.
Riduci gli errori temporanei relativi ai limiti di richieste
Distribuisci le richieste nel tempo ed evita i picchi
Distribuisci le richieste nel tempo anziché inviarne un gran numero contemporaneamente.
I limiti di richieste possono essere applicati su periodi più brevi rispetto all'intervallo visualizzato. Ad esempio, un limite di 60 richieste al minuto può essere applicato anche su intervalli di un secondo. Un breve picco può quindi causare un errore anche se l'utilizzo medio sembra inferiore al limite per minuto.
Anche prompt lunghi e limiti di token di output inutilmente elevati possono contribuire agli errori relativi alla frequenza dei token.
Riprova dopo un'attesa
Per gli errori temporanei relativi ai limiti di richieste:
Verifica se la risposta contiene l'intestazione Retry-After.
Se l'intestazione contiene un intervallo valido, attendi almeno il tempo indicato prima di riprovare.
Se l'intestazione è assente o non valida, usa il backoff esponenziale con jitter: aumenta l'attesa dopo ogni tentativo non riuscito e aggiungi un breve ritardo casuale.
Limita sia il numero di tentativi sia il tempo totale dedicato ai nuovi tentativi.
Gli SDK ufficiali di OpenAI riprovano già in caso di errori idonei relativi ai limiti di richieste e rispettano Retry-After quando è presente. Tieni conto di questi tentativi prima di aggiungere un altro ciclo di ripetizione.
Anche le richieste non riuscite concorrono ai limiti per minuto. Reinviare continuamente la stessa richiesta può prolungare il problema.
Per istruzioni ed esempi di implementazione, consulta la guida ai limiti di richieste dell'API. Esamina attentamente qualsiasi libreria di terze parti per i nuovi tentativi prima di usarla nell'applicazione.
Controlla le dimensioni del prompt e dell'output
Rimuovi dai prompt le istruzioni superflue, il contesto ripetuto e gli esempi non necessari. Verifica il prompt aggiornato per assicurarti che produca ancora il risultato desiderato.
Usa il parametro dei token di output supportato dall'endpoint e dal modello:
Chat Completions usa max_completion_tokens.
Responses usa max_output_tokens.
Evita di impostare un limite molto superiore a quello richiesto. Questi parametri includono sia i token di ragionamento sia l'output visibile: quando usi un modello di ragionamento, considera entrambi.
Controlla il tuo livello di utilizzo
Se gli errori persistono dopo aver ridotto i picchi e verificato l'utilizzo dei token, consulta la pagina Limiti per conoscere le opzioni disponibili per aumentare i limiti.
Con l'aumento della spesa per l'API, OpenAI può assegnare automaticamente all'organizzazione un livello di utilizzo superiore. In genere, questo aumenta i limiti di richieste per la maggior parte dei modelli.
Il limite mensile di utilizzo approvato è distinto dai limiti di frequenza per richieste e token. L'aumento dell'uno non conferma che anche l'altro sia cambiato.
Se il problema persiste
Prima di richiedere assistenza
Tieni a disposizione il messaggio di errore esatto, gli eventuali codici di errore, gli ID delle richieste pertinenti, l'ora dell'errore con il relativo fuso orario e il limite interessato mostrato nel tuo account. Prendi nota dei passaggi che hai già provato.
Contatta l'assistenza OpenAI
Se non riesci a risolvere il problema dopo aver controllato il limite indicato, contatta l'assistenza OpenAI tramite il Centro assistenza. Non includere chiavi API o altri dati riservati di autenticazione.