---
title: "Errori API LLM 401, 402, 409, 429: quando ritentare | BroadRouter"
description: "Cosa significa ogni stato HTTP dell’API di BroadNet Inference, quali ritentare con backoff, quali correggere prima e cosa mandare all’assistenza con l’ID richiesta."
url: https://broadrouter.com/it/guides/errors-and-retries/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/guides/errors-and-retries/) (aggiornato il 2026-11-14).

# Codici di errore di BroadNet Inference e quando ritentare

Aggiornato 2026-11-14

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](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-errors-and-retries&utm_content=body#errors) 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](https://broadrouter.com/it/guides/api-keys-ip-allow-lists/) |
| 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](https://broadrouter.com/it/guides/unlimited-llm-api-sessions/), 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](https://broadrouter.com/it/blog/llm-api-rate-limits-by-provider/).

## Come ritento con l’SDK di OpenAI?

Secondo il suo [README su GitHub](https://github.com/openai/openai-python#retries), 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):

```python
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:

```python
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](https://broadrouter.com/it/glossary/exponential-backoff/).

## 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](https://broadrouter.com/it/glossary/idempotency-key/).

## 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](https://broadrouter.com/it/guides/openai-python-sdk/) mostra come leggere l’header.

## Termini in questa guida

[Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/)

Un rate limit è un tetto che un’API pone a quanto un client può usarla in un intervallo di tempo, per esempio richieste al minuto o token al minuto. Le richieste oltre il limite vengono rifiutate, di solito con HTTP 429 Too Many Requests, finché l’uso non torna sotto la soglia.

[Concorrenza (concurrency)](https://broadrouter.com/it/glossary/concurrency/)

La concorrenza è il numero di richieste che un client ha in corso nello stesso momento. Le API LLM spesso la limitano per chiave o per piano, separatamente dalle richieste al minuto, perché ogni richiesta aperta occupa capacità GPU finché la sua risposta non è terminata.

[Pagamento a consumo (pay-as-you-go)](https://broadrouter.com/it/glossary/pay-as-you-go/)

Il pagamento a consumo è un modello di prezzo in cui paghi solo ciò che usi, misurato per unità come token, richieste o minuti di audio, senza abbonamento né impegno minimo. La maggior parte delle API LLM fattura così, da un saldo prepagato o con una fattura periodica.

[Credito prepagato (prepaid credit)](https://broadrouter.com/it/glossary/prepaid-credit/)

Il credito prepagato è denaro aggiunto a un account API prima dell’uso. Ogni richiesta scala il proprio costo dal saldo e, quando il saldo si esaurisce, le richieste a consumo si fermano finché non ricarichi. Limita la spesa a quanto hai versato.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[Backoff esponenziale (exponential backoff)](https://broadrouter.com/it/glossary/exponential-backoff/)

Il backoff esponenziale è una strategia di retry in cui un client aspetta sempre di più dopo ogni tentativo fallito, di solito raddoppiando il ritardo fino a un tetto, prima di riprovare. Aggiungere un jitter casuale a ogni attesa distribuisce i retry di molti client, così non colpiscono il server nello stesso istante.

[Timeout della richiesta (request timeout)](https://broadrouter.com/it/glossary/request-timeout/)

Il timeout di una richiesta è il tempo massimo che un client HTTP aspetta un server prima di abbandonare la richiesta. I client di solito lo dividono in un timeout di connessione, per aprire la connessione, e un timeout di lettura, per l’attesa dei dati. Le chiamate LLM richiedono timeout di lettura generosi perché le risposte lunghe richiedono tempo.

## 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.

## Guide correlate

-   [Streaming delle chat completions e connessioni interrotte](https://broadrouter.com/it/guides/streaming-chat-completions/)
-   [Limita le chiavi API ai tuoi server con le allowlist di IP](https://broadrouter.com/it/guides/api-keys-ip-allow-lists/)
-   [Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-errors-and-retries&utm_content=page-cta) ·

**Fonti**

-   [Riferimento API di BroadNet Inference, errori e retry (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-errors-and-retries&utm_content=sources#errors)
-   [Riferimento API di BroadNet Inference, limiti (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-errors-and-retries&utm_content=sources#limits)
-   [README dell’SDK Python di OpenAI, retry e timeout (verificato il 2026-11-14)](https://github.com/openai/openai-python#retries)
