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:
- Metti i job in una coda condivisa (Redis, SQS, una tabella del database).
- Esegui un numero fisso di consumer, pari al limite di richieste in corso della chiave.
- Assegna a ogni job un ID e salva i risultati per ID, così un job ritentato non viene eseguito due volte.
- 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.
