BroadRouter
Inizia

Codici di errore di BroadNet Inference e quando ritentare

Aggiornato

Controlla lo stato HTTP prima di interpretare il corpo. Ritenta 429 e 5xx con un backoff esponenziale limitato. Correggi 400, 403, 413 e 422 prima di ritentare. Per un 401 controlla chiave e saldo, per un 402 ricarica l’account. Registra sempre l’header X-Request-ID per l’assistenza.

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 solo broadnet/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=0 dove 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.

Domande frequenti

Devo ritentare un errore 429 di un’API LLM?

Sì, con un backoff esponenziale limitato. Su BroadNet Inference un 429 significa che hai raggiunto un limite di frequenza, di concorrenza, di token al minuto o di spesa. Se succede spesso riduci il parallelismo, e smetti di ritentare quando la causa è un limite di spesa.

Perché ricevo un 401 anche se la chiave è giusta?

Su BroadNet un 401 copre anche una quota a consumo esaurita o un budget bloccato, non solo una chiave sbagliata o scaduta. Controlla il saldo dell’account e lo stato della chiave nella pagina dell’account.

Che differenza c’è qui tra 401 e 403?

Un 401 riguarda la chiave o la quota dell’account. Un 403 significa che la chiave funziona ma la richiesta è rifiutata dalla policy su modello, route o IP, per esempio una chiamata da un indirizzo che non è nella allowlist.

L’SDK di OpenAI ritenta gli errori in automatico?

Sì. L’SDK Python di OpenAI ritenta per impostazione predefinita due volte errori di connessione, 408, 409, 429 e 5xx, con un breve backoff esponenziale. Imposta max_retries per cambiare il numero, oppure 0 per disattivare i retry.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity