NL ▾
API-sleutel aanvragen

LLM API-fout 429: oorzaken en hoe je het oplost

Een LLM API-fout 429 betekent dat de server een verzoek nu weigert, niet definitief. Op deze API zijn er drie verschillende oorzaken, en elk vraagt om een iets andere oplossing.

Bijgewerkt

Pakketjes licht die bij een poort met acht banen wachten, ter illustratie van API-rate limits

Belangrijkste punten

De drie soorten 429

HTTP 429 is de standaardstatus 'te veel verzoeken'. Hier dekt het drie situaties, en het JSON-foutlichaam vertelt je welke.

Error codeWat het betekentTypische oplossing
rate_limitedTe veel verzoeken per minuutVertraag, verdeel verzoeken over de minuut
concurrencyTe veel verzoeken die tegelijk lopenVerminder parallelisme, wacht tot er weer slots vrijkomen
Overbelasting, met Retry-After: 5Tijdelijke belasting van de service, niet jouw schuldWacht het aantal seconden uit de header en probeer opnieuw

Lees eerst de code, want een oplossing voor één oorzaak helpt bij een andere niets. Je verzoeken per minuut halveren helpt niet als het echte probleem is dat 20 workers tegelijk afvuren.

Ken je limieten

De limieten hangen af van het type sleutel:

  • Volledige sleutel: 8 gelijktijdige verzoeken en 300 verzoeken per minuut.
  • Proefsleutel: 2 gelijktijdige verzoeken en 60 verzoeken per minuut.

Elk antwoord bevat X-RateLimit-Limit-Requests en X-RateLimit-Limit-Concurrency, zodat je client de bovengrens kunt uitlezen in plaats van deze hard te coderen. De proefsleutel is de gebruikelijke boosdoener voor nieuwe gebruikers: een script dat het goed doet met 1 verzoek tegelijk, begint te falen zodra je een thread pool van 4 toevoegt. De proef is bedoeld voor testen, en een volledige sleutel krijg je bij elke opwaardering vanaf $20 (zie de prijzenpagina voor bedragen en bonussen).

De bovenstaande cijfers gelden per sleutel. Als één sleutel wordt gedeeld door een webapp, een cronjob en het notebook van een collega, trekken ze allemaal uit hetzelfde totaal, en lijken de 429's willekeurig totdat je de drie werklasten optelt.

Waarom streaming gelijktijdigheidsfouten waarschijnlijker maakt

Een normaal verzoek houdt een gelijktijdigheids-slot een seconde of twee vast. Een gestreamd verzoek (stream: true) houdt het vast tot het laatste token is aangekomen en de stream sluit. Een lang antwoord kan een slot tientallen seconden bezet houden, dus 8 slots zijn snel op in een chatapp met meerdere actieve gebruikers.

Twee fouten veroorzaken het meeste probleem hier. De eerste is een stream verlaten zonder deze te sluiten: als de client stopt met lezen maar de verbinding open laat, blijft de slot bezet tot de verbinding eindigt. Sluit altijd het antwoord in een finally-blok, of gebruik de contextmanager van de SDK. De tweede is een stream opnieuw proberen door een tweede te openen terwijl de eerste nog actief is, wat de slotgebruiking precies verdubbelt op het moment dat je weinig slots hebt.

Als je app meer gelijktijdige lange streams nodig heeft dan je sleutel toestaat, zet dan nieuwe chats in de wachtrij aan je eigen kant en toon een korte wachttijd. Dat is beter dan gebruikers ruwe fouten te laten zien.

Python-code voor opnieuw proberen met backoff

Het patroon is eenvoudig: vang de 429, lees de code, wacht, probeer opnieuw met een groeiende vertraging en wat willekeurigheid, en geef op na een paar pogingen. Deze versie gebruikt het officiële openai-pakket tegen de basis-URL van de service:

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."}]))

Wanneer de header aanwezig is, gebruik deze dan als minimale wachttijd. Wanneer deze ontbreekt, werkt de exponentiële vertraging voor rate_limited omdat het venster per minuut voortschrijdt. De jitter voorkomt dat veel workers op hetzelfde moment opnieuw proberen.

Beperk gelijktijdige aanroepen zodat je zelden een 429 ziet

Retries behandelen het symptoom. Een semaphore voorkomt de meeste fouten door niet meer te verzenden dan je slotaantal. Stel deze iets onder de limiet zodat een retry of een dwaas verzoek nog ruimte heeft:

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())

Voor de limiet per minuut zijn 300 verzoeken per minuut gemiddeld 5 per seconde. Als je duizenden korte taken in batches verwerkt, voeg dan een korte slaap of een tokenemmer toe voor de semaphore. Omdat de SDK ook standaard zelf opnieuw probeert, stel max_retries expliciet in zodat je eigen logica en die van de SDK niet stapelen en de wachttijden vermenigvuldigen.

Reproduceer en inspecteer een 429 met curl

Voordat je code aanpast, kijk naar de ruwe respons. Voeg -i toe aan curl zodat de headers worden afgedrukt, en stuur een paar verzoeken parallel om de fout opzettelijk te provoceren:

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

Op een proefsleutel, die 2 verzoeken tegelijk toestaat, zouden de derde en vierde aanroepen status 429 moeten geven met een error code van concurrency. Bij een volledige sleutel zou je meer dan 8 tegelijk nodig hebben. Kijk naar drie dingen in elke reply: de statusregel, de Retry-After-header als die er is, en het error.code-veld in de JSON-body. Dit kleine experiment vertelt je meer dan een uur raden, en het geeft je een reproduceerbaar geval om te tonen aan support als er iets mis lijkt te zijn.

Ontwerp erop, niet eromheen

Behandel een 429 als een normaal evenement, zoals een time-out. Plaats modelaanroepen achter één functie, log elke retry met de reden, en exposeer een teller zodat je merkt wanneer de retries stijgen. Een stijgende retry-rate is een vroeg teken dat je verkeer de limieten van één sleutel te boven gaat, lang voordat gebruikers klagen. Voor chatproducten houdt een kleine in-memory wachtrij per gebruiker één druk account ervan af om alle 8 slots van de andere gebruikers in beslag te nemen.

Een korte foutopsporingslijst

  1. Log het volledige foutbericht en de X-Request-Id-header voor elke 429. Het veld 'code' onderscheidt rate_limited van concurrency.
  2. Controleer of je sleutel een proefsleutel is. Zo ja, verwacht dan 2 gelijktijdige verzoeken en 60 per minuut.
  3. Tel elk programma dat de sleutel gebruikt, niet alleen degene die faalde.
  4. Zoek naar niet-gesloten streams, en naar loops die direct opnieuw proberen zonder vertraging. Een directe retry-loop verandert één 429 in honderd.
  5. Bevestig het saldo met X-Balance-USD of GET /v1/balance. Een leeg saldo is een ander probleem dan een 429, maar controleren duurt enkele seconden.

Mislukte verzoeken worden niet in rekening gebracht, dus opnieuw proberen kost je geen tokens voor de afgewezen pogingen. Voor de volledige lijst van statuscodes en headers, zie de documentatie. Als je een sleutel nodig hebt met hogere limieten dan een proefsleutel, vraag een API-sleutel aan en laad op.

Vragen en antwoorden

Is een 429 mijn schuld of die van de provider?

Beide is mogelijk. De codes rate_limited en concurrency betekenen dat je sleutel zijn limiet heeft overschreden. Een 429 met een Retry-After-header kan ook komen door tijdelijke overbelasting; wachten op de aangegeven tijd en dan opnieuw proberen is de juiste reactie.

Hoe lang moet ik wachten voordat ik het opnieuw probeer?

Als de respons een Retry-After-header heeft, wacht dan minimaal dat aantal seconden. Begin anders met één seconde en verdubbel de vertraging elke keer, met een beetje willekeurige jitter.

Kost dit geld als verzoeken worden afgewezen?

Nee. Mislukte of geweigerde verzoeken worden niet aangerekend.

Kan ik mijn limieten verhogen?

Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 per minuut toe, tegenover 2 en 60 voor een proefsleutel. Verdeel je werk daarboven over een wachtrij aan je eigen kant.

Je sleutel is nog maar één webformulier verwijderd

Maak een account aan, kopieer de sleutel, pas de base URL aan. Dat is de hele setup.