IT ▾
Ottieni la chiave API

Errore API LLM 429: cause e come risolverlo

Un errore API LLM 429 significa che il server rifiuta momentaneamente una richiesta, non definitivamente. Su questa API ci sono tre cause distinte e ognuna richiede una correzione leggermente diversa.

Aggiornato

Pacchetti di luce in coda a un cancello con otto corsie, che illustrano i limiti di richiesta dell'API

Punti chiave

I tre tipi di 429

HTTP 429 è lo status standard "troppe richieste". Qui copre tre situazioni e il corpo JSON dell'errore ti dice in quale ti trovi.

Codice di erroreCosa significaSoluzione tipica
rate_limitedTroppe richieste al minutoRallenta, distribuisci le richieste nel minuto
concurrencyTroppe richieste in esecuzione contemporaneamenteRiduci il parallelismo, attendi che gli slot si liberino
Sovraccarico, con Retry-After: 5Carico temporaneo del servizio, non è colpa tuaAttendi il numero di secondi indicato nell'header, poi riprova

Leggi prima il codice, perché una soluzione per una causa non vale per le altre. Ridurre a metà le richieste al minuto non aiuterà se il problema reale è che 20 worker sparano richieste simultaneamente.

Conosci i tuoi limiti

I limiti dipendono dal tipo di chiave:

  • Chiave completa: 8 richieste concurrent e 300 richieste al minuto.
  • Chiave trial: 2 richieste concurrent e 60 richieste al minuto.

Ogni risposta include X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency, così il tuo client può leggere il limite massimo senza doverlo impostare manualmente. La chiave di prova è spesso la causa per i nuovi utenti: uno script che funziona bene con 1 richiesta alla volta inizia a fallire quando aggiungi un thread pool da 4. La prova serve per i test e una chiave completa è disponibile con qualsiasi ricarica da $20 (vedi la pagina dei prezzi per importi e bonus).

I numeri sopra sono per chiave. Se una chiave è condivisa da un'app web, un cron job e il notebook di un collega, tutti attingono allo stesso pool e i 429 sembreranno casuali finché non sommerai i tre carichi di lavoro.

Perché lo streaming rende più probabili gli errori di concorrenza

Una richiesta normale mantiene uno slot di concorrenza per un secondo o due. Una richiesta in streaming (stream: true) lo mantiene fino all'arrivo dell'ultimo token e alla chiusura dello stream. Una risposta lunga può tenere occupato uno slot per decine di secondi, quindi 8 slot spariscono rapidamente in un'app chat con diversi utenti attivi.

Due errori causano la maggior parte dei problemi qui. Il primo è abbandonare uno stream senza chiuderlo: se il client smette di leggere ma lascia la connessione aperta, lo slot rimane occupato fino alla chiusura della connessione. Chiudi sempre la risposta in un blocco finally, o usa il context manager dell'SDK. Il secondo è ritentare uno stream aprendone un secondo mentre il primo è ancora vivo, il che raddoppia l'uso degli slot proprio quando ne sei a corto.

Se la tua app ha bisogno di più stream lunghi simultanei di quanto permetta la tua chiave, accoda le nuove chat lato client e mostra un breve stato di attesa. È meglio che far vedere errori grezzi agli utenti.

Codice di retry Python con backoff

Il pattern è semplice: intercetta il 429, leggi il codice, attendi, riprova con un ritardo crescente e un po' di casualità, e arrenditi dopo alcuni tentativi. Questa versione usa il pacchetto ufficiale openai contro l'URL base del servizio:

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
    max_retries=0,  # we handle retries ourselves
)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=messages,
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            headers = e.response.headers
            wait = float(headers.get("Retry-After", 0))
            if not wait:
                wait = min(30, 2 ** i)  # 1, 2, 4, 8, 16 seconds
            wait += random.uniform(0, 1)  # jitter
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

print(chat([{"role": "user", "content": "Reply with the word ok."}]))

Quando l'header è presente, usalo come attesa minima. Quando manca, il ritardo esponenziale funziona per rate_limited perché la finestra per minuto si sposta. Il jitter evita che molti worker ritentino nello stesso istante.

Imposta un tetto alle chiamate parallele così raramente vedrai un 429

I retry trattano il sintomo. Un semaforo previene la maggior parte dei casi impedendo di inviare più richieste del tuo conteggio di slot. Impostalo leggermente al di sotto del limite così un retry o una richiesta isolata abbiano ancora spazio:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6)  # full key allows 8; use 1 on a trial key

async def ask(prompt):
    async with sem:
        r = await client.chat.completions.create(
            model="uncensored",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main():
    prompts = [f"Give one fact about the number {n}." for n in range(50)]
    results = await asyncio.gather(*(ask(p) for p in prompts))
    print(len(results))

asyncio.run(main())

Per il limite al minuto, 300 richieste al minuto sono in media 5 al secondo. Se batchezi migliaia di lavori brevi, aggiungi un piccolo sleep o un token bucket davanti al semaphore. Poiché l'SDK ritenta anche in modo autonomo per impostazione predefinita, imposta max_retries esplicitamente così la tua logica e quella dell'SDK non si impilano e moltiplicano i tempi di attesa.

Riproduci e ispeziona un 429 con curl

Prima di modificare il codice, guarda la risposta grezza. Aggiungi -i a curl così gli header vengono stampati, e lancia alcune richieste in parallelo per provocare l'errore intenzionalmente:

for i in 1 2 3 4; do
  curl -i -s https://api.onekeyllmapi.com/v1/chat/completions     -H "Authorization: Bearer $API_KEY"     -H "Content-Type: application/json"     -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait

Su una chiave di prova, che permette 2 richieste alla volta, la terza e la quarta chiamata dovrebbero restituire status 429 e un codice di errore di concurrency. Con una chiave completa avresti bisogno di più di 8 simultanee. Guarda tre cose in ogni risposta: la riga di status, l'header Retry-After se presente, e il campo error.code nel corpo JSON. Questo piccolo esperimento ti dice più di un'ora di indovinare, e ti dà un caso riproducibile da mostrare al supporto se qualcosa sembra sbagliato.

Progetta per gestirlo, non per aggirarlo

Tratta un 429 come un evento normale, come un timeout. Metti le chiamate al modello dietro una funzione, registra ogni tentativo con il suo motivo ed esponi un contatore così noti quando i tentativi aumentano. Un tasso di tentativi crescente è un segnale precoce che il tuo traffico ha superato i limiti di una singola chiave, molto prima che gli utenti si lamentino. Per i prodotti chat, una piccola coda in memoria per utente impedisce a un account occupato di prendersi tutti gli 8 slot degli altri utenti.

Una breve checklist di debug

  1. Logga il corpo completo dell'errore e l'header X-Request-Id per ogni 429. Il campo code separa rate_limited da concurrency.
  2. Verifica se la tua chiave è una chiave di prova. Se sì, prevedi 2 richieste concorrenti e 60 al minuto.
  3. Conta ogni programma che usa la chiave, non solo quello che ha fallito.
  4. Cerca flussi non chiusi e cicli che ritentano istantaneamente senza ritardo. Un ciclo di ritentativi istantaneo trasforma un 429 in cento.
  5. Conferma il saldo con X-Balance-USD o GET /v1/balance. Un saldo vuoto è un problema diverso da un 429, ma controllarlo richiede secondi.

Le richieste fallite non vengono addebitate, quindi ritentare non ti costa token per i tentativi rifiutati. Per l'elenco completo degli status code e degli header, vedi la documentazione. Se hai bisogno di una chiave con limiti superiori a una prova, richiedi una chiave API e ricarica il credito.

Domande e risposte

L'errore 429 è colpa tua o del provider?

Entrambe le opzioni sono possibili. I codici rate_limited e concurrency indicano che la tua chiave ha superato il limite. Un 429 con header Retry-After può anche derivare da un sovraccarico temporaneo; attendere il tempo indicato e riprovare è la risposta corretta.

Quanto devo aspettare prima di riprovare?

Se la risposta include l'header Retry-After, attendi almeno quel numero di secondi. Altrimenti, inizia con un secondo e raddoppia il ritardo ogni volta, aggiungendo un leggero jitter casuale.

Le richieste rifiutate costano denaro?

No. Le richieste fallite o rifiutate non vengono addebitate.

Posso aumentare i miei limiti?

Una chiave completa permette 8 richieste parallele e 300 al minuto, contro 2 e 60 per una chiave di prova. Oltre questo limite, distribuisci il lavoro su una coda lato client.

La tua chiave è a un modulo HTML di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.