L’API renvoie un statut HTTP classique et un code d’erreur lisible par machine. Choisissez l’étape suivante d’après le statut. Ce tableau suit la référence de l’API de BroadNet.
| Statut | Signification | Que faire |
|---|---|---|
| 400 / 422 | Requête ou champ invalide | Corriger d’abord la requête |
| 401 | Clé absente, invalide ou expirée, budget à l’usage bloqué ou quota épuisé | Vérifier le statut de la clé et le solde du compte |
402 insufficient_balance |
Le compte ne peut pas couvrir un achat ; le corps indique le solde et le prix | Alimenter le compte, puis réessayer |
| 403 | Refus par une politique de modèle, de route ou d’IP | Corriger l’incohérence, par exemple une liste d’IP autorisées |
| 409 | Conflit avec l’état du compte : mint_in_progress, key_limit_reached, credential_limit_reached, key_pending |
Ne réessayer que mint_in_progress, avec le même request_id |
| 413 | Requête trop volumineuse ; les fichiers de transcription sont plafonnés à 26 214 400 octets | Réduire la requête |
| 429 | Limite de débit, de concurrence, de tokens par minute ou de dépenses atteinte | Lire le détail de la réponse, patienter avec un backoff et réessayer |
| 500 / 502 / 503 / 504 | Traitement côté serveur | Réessayer avec un backoff exponentiel borné ; réutiliser le même request_id pour les achats de clés horaires |
La documentation de BroadNet indique de vérifier le statut HTTP avant d’analyser un corps JSON, puis de lire le code error lisible par machine s’il existe.
Quelles limites provoquent un 429 ?
Une clé à l’usage autorise 30 requêtes par minute et 4 requêtes en cours simultanément. Selon la documentation de BroadNet, une clé horaire autorise 120 requêtes par minute, un flux et 300,000 tokens par minute. Avec un forfait illimité, chaque session traite une requête à la fois. Pour comparer ces limites avec celles d’OpenAI, Anthropic, Groq et DeepSeek, lisez les limites de débit des API LLM par fournisseur.
Comment réessayer avec le SDK OpenAI ?
D’après son README sur GitHub, le SDK Python d’OpenAI réessaie déjà deux fois par défaut les erreurs de connexion et les réponses 408, 409, 429 et 5xx, avec un court backoff exponentiel. Son délai d’attente par défaut est de 10 minutes. Définissez les deux explicitement :
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
)
Les commentaires du code signifient : max_retries=0 désactive les nouvelles tentatives automatiques, et le timeout (en secondes) est à augmenter pour les longues réponses de raisonnement.
Comment écrire mon propre backoff ?
Si vous appelez l’API sans SDK, plafonnez à la fois le nombre d’essais et l’attente :
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
Ne réessayez jamais un 400, 403, 413 ou 422 sans rien changer : la même requête échoue de la même façon. Chaque nouvelle tentative d’une requête de chat est une nouvelle inférence, facturée à nouveau en paiement à l’usage. Le schéma général est décrit dans backoff exponentiel.
Réessayer sans risque l’achat d’une clé horaire
POST /portal/keys/hourly accepte un request_id. Après un délai dépassé, une connexion perdue, un 409 mint_in_progress ou un 5xx, réessayez avec le même request_id. Un request_id réutilisé ne crée ni ne facture jamais une deuxième clé ; la répétition renvoie already_issued: true et l’alias. Ne générez jamais un nouvel identifiant tant que vous ne connaissez pas le premier résultat. Plus de détails sur les clés d’idempotence.
Dépannage
- 401 juste après une recharge. La page du compte de BroadNet affiche le dernier quota enregistré et indique qu’un changement de financement est en cours de mise à jour pendant son application. Actualisez la page et réessayez une fois l’opération terminée.
- 429 avec seulement quelques requêtes par minute. Vous atteignez probablement la limite de 4 requêtes simultanées, par exemple avec de longs flux en parallèle. Utilisez un petit pool de workers.
- 403 sur un modèle mais pas sur un autre. La politique de la clé ne couvre pas ce modèle ou cette route. Les clés de forfait, par exemple, sont prévues pour
broadnet/deepseek-v4.1-flash, et une clé horaire ne couvre quebroadnet/gemma-4-26b-a4b. - Le SDK a réessayé et vous avez été facturé deux fois. Une requête de chat réessayée est une nouvelle inférence. Définissez
max_retries=0là où une réponse en double coûte plus cher qu’un échec.
Quoi envoyer au support
Indiquez la valeur de l’en-tête X-Request-ID, l’horodatage UTC, la route, le statut HTTP et l’alias de votre clé. N’envoyez jamais la clé elle-même. Le guide du SDK Python d’OpenAI montre comment lire l’en-tête.
