L’API restituisce un normale stato HTTP e un codice di errore leggibile dalle macchine. Scegli il passo successivo in base allo stato. Questa tabella segue il riferimento API di BroadNet.
| Stato | Cosa significa | Cosa fare |
|---|---|---|
| 400 / 422 | Richiesta o campo non valido | Correggi prima la richiesta |
| 401 | Chiave mancante, non valida o scaduta, budget a consumo bloccato o quota esaurita | Controlla lo stato della chiave e il saldo dell’account |
402 insufficient_balance |
L’account non copre un acquisto; il corpo riporta saldo e prezzo | Ricarica l’account, poi riprova |
| 403 | Rifiutata dalla policy su modello, route o IP | Correggi la discrepanza, per esempio una allowlist di IP |
| 409 | In conflitto con lo stato dell’account: mint_in_progress, key_limit_reached, credential_limit_reached, key_pending |
Ritenta solo mint_in_progress, con lo stesso request_id |
| 413 | Richiesta troppo grande; i file da trascrivere hanno un limite di 26.214.400 byte | Riduci la richiesta |
| 429 | Raggiunto un limite di frequenza, concorrenza, token al minuto o spesa | Leggi i dettagli della risposta, attendi con backoff e ritenta |
| 500 / 502 / 503 / 504 | Elaborazione lato server | Ritenta con backoff esponenziale limitato; per gli acquisti di chiavi orarie riusa lo stesso request_id |
La documentazione di BroadNet dice di controllare lo stato HTTP prima di interpretare un corpo JSON, e poi di leggere il codice error leggibile dalle macchine, quando c’è.
Quali limiti causano un 429?
Una chiave a consumo consente 30 richieste al minuto e 4 richieste contemporanee. Secondo la documentazione di BroadNet, una chiave oraria ha 120 richieste al minuto, uno stream e 300,000 token al minuto. Con un piano illimitato, ogni sessione esegue una richiesta alla volta. Per confrontare questi limiti con OpenAI, Anthropic, Groq e DeepSeek, leggi i rate limit delle API LLM per provider.
Come ritento con l’SDK di OpenAI?
Secondo il suo README su GitHub, l’SDK Python di OpenAI ritenta già per impostazione predefinita due volte errori di connessione e risposte 408, 409, 429 e 5xx, con un breve backoff esponenziale. Il timeout predefinito è di 10 minuti. Imposta entrambi in modo esplicito (nel codice, i commenti dicono che 0 disattiva i retry automatici e che il timeout, in secondi, va alzato per le risposte con ragionamenti lunghi):
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
max_retries=4, # 0 turns automatic retries off
timeout=120, # seconds; raise it for long reasoning answers
)
Come scrivo un backoff mio?
Se chiami l’API senza un SDK, limita sia il numero di tentativi sia l’attesa:
import random, time, requests
RETRY = {429, 500, 502, 503, 504}
def post_with_backoff(url, headers, body, tries=5):
for attempt in range(tries):
r = requests.post(url, headers=headers, json=body, timeout=120)
if r.status_code not in RETRY:
return r # success, or an error to fix rather than retry
time.sleep(min(30, 2 ** attempt) + random.random())
return r
Non ritentare mai 400, 403, 413 o 422 senza modifiche: la stessa richiesta fallisce allo stesso modo. Ogni retry di una richiesta di chat è una nuova inferenza e, a consumo, viene fatturato di nuovo. Lo schema generale è spiegato in backoff esponenziale.
Ritentare in sicurezza l’acquisto di una chiave oraria
POST /portal/keys/hourly accetta un request_id. Dopo un timeout, una connessione persa, un 409 mint_in_progress o un 5xx, ritenta con lo stesso request_id. Un request_id riutilizzato non crea né addebita mai una seconda chiave; la ripetizione restituisce already_issued: true e l’alias. Non generare mai un nuovo id finché non conosci l’esito del primo. Approfondisci in chiavi di idempotenza.
Risoluzione dei problemi
- 401 subito dopo una ricarica. La pagina dell’account di BroadNet mostra l’ultima quota registrata e segna una variazione di fondi come in aggiornamento mentre viene applicata. Ricarica la pagina e riprova quando ha finito.
- 429 con poche richieste al minuto. Probabilmente stai toccando il limite di concorrenza di 4 richieste, per esempio con stream lunghi in parallelo. Usa un piccolo pool di worker.
- 403 su un modello ma non su un altro. La policy della chiave non copre quel modello o quella route. Le chiavi dei piani, per esempio, sono per
broadnet/deepseek-v4.1-flash, e una chiave oraria copre solobroadnet/gemma-4-26b-a4b. - L’SDK ha ritentato e ti è stato addebitato due volte. Una richiesta di chat ritentata è una nuova inferenza. Imposta
max_retries=0dove una risposta duplicata costa più di una fallita.
Cosa mandare all’assistenza
Includi il valore dell’header X-Request-ID, l’orario UTC, la route, lo stato HTTP e l’alias della chiave. Non mandare mai la chiave. La guida all’SDK Python di OpenAI mostra come leggere l’header.
