BroadRouter

Errore 429 nelle API LLM: backoff, jitter e limitatori

A cura del team di BroadNet Inference · 5 min di lettura · Pubblicato · Aggiornato

Un 429 significa che hai raggiunto un limite di frequenza, di concorrenza o di spesa. Ritenta con un backoff esponenziale limitato e jitter casuale, e rispetta Retry-After quando c’è. Poi previeni gran parte dei 429: limita le richieste in corso con un semaforo al limite della chiave e metti in coda le altre. Ritenta i 5xx allo stesso modo; gli altri 4xx vanno corretti.

Un 429 significa che il tuo traffico ha superato un rate limit: richieste al minuto, richieste in corso, token al minuto o spesa. Si risolve in due parti. Ritentare bene: backoff esponenziale limitato con jitter casuale, rispettando Retry-After. Inviare meno richieste insieme: un semaforo al limite di richieste in corso della chiave, più una coda. Trovi entrambe qui sotto, con il codice.

Per l’elenco completo dei codici di stato, vedi la guida a errori e retry; per esecuzioni di agenti lunghe ore con checkpoint e timeout, vedi agenti a lunga esecuzione: timeout e retry.

Che differenza c’è tra 429 e 5xx?

Stato Di chi è il problema Ritentare? Come
429 Il tuo traffico ha superato un limite Sì Backoff con jitter; rispetta Retry-After; riduci la concorrenza
500 / 502 / 503 / 504 Lato server Sì Backoff esponenziale limitato
Connessione interrotta, timeout Rete o server Di solito Backoff; per gli stream, solo se una nuova fattura è accettabile
400 / 422 Richiesta errata No Correggi il payload
401 / 402 / 403 Chiave, saldo o policy No Correggi la chiave, ricarica l’account, correggi l’allowlist
413 Richiesta troppo grande No Riducila

Su BroadNet Inference un 429 può indicare uno qualsiasi di quattro limiti: frequenza, concorrenza, token al minuto o spesa. Un limite di spesa non si sblocca in 30 secondi. La documentazione di BroadNet non dice quale campo del corpo dell’errore indichi il limite, quindi registra il corpo e confrontalo con i limiti mostrati nei dettagli della tua chiave.

Il nostro dataset aperto su free tier e rate limit delle API LLM confronta quello che 14 provider pubblicano su accesso gratuito, rate limit iniziali, carta di credito richiesta e addestramento sui dati del free tier, con fonte e data per ogni valore.

Quali limiti causano i 429?

Conosci i numeri con cui hai a che fare. Su BroadNet Inference:

Tipo di chiave Richieste / minuto In corso Altro
A consumo 30 4 Budget di spesa condiviso
Chiave oraria 120 1 stream 300,000 token / minuto
Sessione di un piano illimitato — 1 richiesta per sessione Nessun contatore di token

Per gli LLM conta soprattutto il numero di richieste in corso. Una risposta in streaming tiene occupato il suo slot finché non arriva l’ultimo token, quindi una risposta lunga lo impegna per tutto il tempo che il modello impiega a scriverla (BroadNet indica una velocità tipica di circa 100 token al secondo). Se invii più chiamate in parallelo dei 4 slot della chiave, quelle in eccesso ricevono un 429, anche se in quel minuto hai inviato solo una manciata di richieste. È un problema di concorrenza, e il solo backoff lo gestisce male. Per dimensionare i worker rispetto a un limite prima del lancio, usa il calcolatore dei rate limit LLM gratuito. Per un job fisso con molti elementi, il pianificatore di job batch LLM trasforma gli stessi limiti in un tempo di esecuzione. Gli altri provider contano in modo diverso (token al minuto, richieste al giorno o richieste in corso); i rate limit delle API LLM per provider ne confronta 13, a partire dalla loro documentazione.

Come si scrive un backoff con jitter?

Il semplice backoff esponenziale attende 1, 2, 4, 8 secondi. Se cento worker sono stati limitati nello stesso momento, tornano tutti nello stesso momento. Nella simulazione di AWS con 100 client in competizione, il full jitter ha più che dimezzato il numero di chiamate e ha finito prima del backoff senza jitter. La versione più semplice, il full jitter, attende un tempo casuale tra zero e il tetto esponenziale:

import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError, APIConnectionError) as e:
            status = getattr(e, "status_code", None)
            if status is not None and status not in RETRYABLE:
                raise  # 400, 401, 403...: retrying will not help
            if attempt == max_attempts - 1:
                raise
            retry_after = None
            if getattr(e, "response", None) is not None:
                retry_after = e.response.headers.get("retry-after")
            wait = random.uniform(0, min(cap, base * 2 ** attempt))
            if retry_after and retry_after.isdigit():
                wait = max(wait, float(retry_after))
            time.sleep(wait)

max_retries=0 disattiva i retry dell’SDK, così non ritenti due volte. Se il comportamento integrato dell’SDK ti basta, funziona anche il contrario: rinuncia al tuo loop e imposta max_retries=4 sul client, come mostra la guida all’SDK Python. Gli SDK ufficiali per Python e Node ritentano per impostazione predefinita errori di connessione, 408, 409, 429 e 5xx due volte.

Retry-After è un header standard (RFC 9110) che può contenere secondi o una data. La documentazione di BroadNet non lo garantisce, quindi il codice lo tratta come opzionale.

Come si prevengono i 429?

Limita le richieste in corso al limite della chiave. In Python basta un asyncio.Semaphore: un solo oggetto e un solo blocco async with. Il codice usa 4 come esempio; impostalo sul limite di richieste in corso della tua chiave (4 su una chiave BroadNet a consumo):

import asyncio, os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4)  # match the key's in-flight limit

async def ask(prompt):
    async with slots:
        r = await client.chat.completions.create(
            model="broadnet/gemma-4-26b-a4b",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))

gather avvia tutti i task, ma ne girano insieme solo quanti il semaforo ne consente. Gli altri aspettano nella coda del semaforo. In Node, il pacchetto p-limit fa la stessa cosa, sempre con 4 come valore di esempio:

// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit

async function ask(prompt) {
  const r = await client.chat.completions.create({
    model: "broadnet/gemma-4-26b-a4b",
    messages: [{ role: "user", content: prompt }],
  });
  return r.choices[0].message.content;
}

const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));

Se ti serve anche un tetto al minuto, aggiungi un token bucket che rilascia un permesso ogni 60 / rpm secondi, dove rpm è il limite di richieste al minuto della tua chiave (30 su una chiave BroadNet a consumo).

Quando ti serve una vera coda?

Un semaforo vive in un solo processo. Quando più worker o server condividono una chiave, il limite è condiviso e ogni processo vede solo il proprio traffico. A quel punto:

  1. Metti i job in una coda condivisa (Redis, SQS, una tabella del database).
  2. Esegui un numero fisso di consumer, pari al limite di richieste in corso della chiave.
  3. Assegna a ogni job un ID e salva i risultati per ID, così un job ritentato non viene eseguito due volte.
  4. Fai passare il traffico interattivo e quello batch da chiavi o code separate, così un arretrato batch non blocca mai un utente che aspetta una risposta.

Per un job massivo di migliaia di elementi senza una Batch API, vedi il runner batch riprendibile.

Quali errori nei retry trasformano i 429 in disservizi?

  • Retry senza limite. Un loop di retry senza tetto durante un lungo disservizio moltiplica il carico e, con la fatturazione per token, la fattura.
  • Ritentare alla cieca uno stream a metà. Se lo stream ha già restituito token, un retry è una nuova inferenza e l’utente potrebbe vedere il testo due volte. Vedi l’articolo sullo streaming per riconoscere gli stream incompleti.
  • Ritentare gli errori di account. Un 401 per un plafond a consumo esaurito o un 402 per saldo insufficiente non si risolvono da soli.

Registra ogni retry con il suo stato, il tempo di attesa e l’header di risposta X-Request-ID, che la documentazione di BroadNet chiede di conservare per l’assistenza. Un tasso di retry in crescita è il primo segnale che ti serve più capacità; il logging dell’utilizzo mostra come registrarlo.

Dove si colloca BroadNet Inference

I limiti di BroadNet sono pubblicati e abbastanza bassi da doverci progettare intorno: 4 richieste in corso su una chiave a consumo. Vanno bene per app e agenti, ma sono troppo stretti per un job massivo che vuole centinaia di chiamate in parallelo su una sola chiave. Per gli agenti, un piano illimitato non ha contatore di token ed esegue una richiesta alla volta per sessione; per il lavoro in parallelo aggiungi sessioni, come descritto in eseguire agenti di coding in parallelo. I limiti attuali sono nel riferimento API.

Domande frequenti

Che cosa significa l’errore HTTP 429 in un’API LLM?

Too Many Requests. Hai superato un limite su richieste al minuto, richieste in corso, token al minuto o spesa. La richiesta non è stata elaborata, quindi puoi reinviarla senza rischi dopo un’attesa.

Quanto devo aspettare prima di ritentare dopo un 429?

Usa Retry-After se il server lo invia. Altrimenti parti da circa un secondo, raddoppia a ogni tentativo, fissa un tetto intorno ai 30-60 secondi e scegli un’attesa casuale tra zero e quel tetto. Fermati dopo quattro-sei tentativi.

Devo ritentare gli errori 500 e 503 di un’API LLM?

Sì, con lo stesso backoff limitato. Sono errori lato server. Un 400, 401, 403 o 422 fallirà ogni volta allo stesso modo, quindi va corretto.

L’SDK di OpenAI ritenta i 429 in automatico?

Sì. Gli SDK ufficiali per Python e Node ritentano per impostazione predefinita errori di connessione, 408, 409, 429 e 5xx due volte, con un breve backoff esponenziale. Aumenta max_retries per i job batch e aggiungi un tuo limite di concorrenza.

Perché ricevo un 429 se sono sotto il limite di richieste al minuto?

Di solito è il limite di concorrenza. Le risposte lunghe in streaming restano in corso per molti secondi, quindi poche chiamate in parallelo possono raggiungere il tetto di richieste in corso mentre il conteggio al minuto sembra basso.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity