API は通常の HTTP ステータスと、機械可読なエラーコードを返します。次にどうするかはステータスで決めてください。この表は BroadNet の API リファレンスに沿っています。
| ステータス | 意味 | 対処 |
|---|---|---|
| 400 / 422 | リクエストまたはフィールドが無効 | まずリクエストを修正する |
| 401 | キーがない・無効・期限切れ、従量課金の予算がブロックされている、または利用枠を使い切った | キーの状態とアカウント残高を確認する |
402 insufficient_balance |
アカウントで購入代金をまかなえない。ボディに残高と価格が入る | アカウントに入金してから再試行する |
| 403 | モデル、ルート、IP のポリシーで拒否された | 不一致を直す。例:IP 許可リスト |
| 409 | アカウントの状態と競合:mint_in_progress、key_limit_reached、credential_limit_reached、key_pending |
リトライするのは mint_in_progress だけ。同じ request_id を使う |
| 413 | リクエストが大きすぎる。文字起こしのファイルは 26,214,400 バイトまで | リクエストを小さくする |
| 429 | レート、同時実行数、トークンレート、または支出の上限に達した | レスポンスの詳細を読み、待ってからリトライする |
| 500 / 502 / 503 / 504 | サーバー側の処理 | 上限を設けた指数バックオフでリトライする。時間制キーの購入では同じ request_id を再利用する |
BroadNet のドキュメントでは、JSON ボディをパースする前に HTTP ステータスを確認し、そのうえで機械可読な error コードがあれば読むよう説明しています。
429 の原因になる上限は?
従量課金のキーは毎分 30 リクエスト、同時実行 4 リクエストまでです。BroadNet のドキュメントでは、時間制キーは毎分 120 リクエスト、1 ストリーム、毎分 300,000 トークンです。無制限プランでは、1 セッションにつき同時に 1 リクエストを処理します。これらの上限を OpenAI、Anthropic、Groq、DeepSeek と比べるには、プロバイダー別の LLM API レート制限を読んでください。
OpenAI SDK でリトライするには?
GitHub の README によると、OpenAI Python SDK は接続エラー、408、409、429、5xx のレスポンスを、デフォルトで 2 回、短い指数バックオフでリトライします。デフォルトのタイムアウトは 10 分です。どちらも明示的に設定してください。
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
)
コード内のコメントの意味は、max_retries=0 で自動リトライが止まること、timeout の単位は秒で、推論が長い回答では値を上げることです。
独自のバックオフを書くには?
SDK を使わずに API を呼ぶ場合は、試行回数と待ち時間の両方に上限を設けてください。
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
400、403、413、422 を内容を変えずにリトライしてはいけません。同じリクエストは同じように失敗します。チャットのリクエストをリトライするたびに新しい推論になり、従量課金ではもう一度課金されます。一般的なパターンは指数バックオフを参照してください。
時間制キーの購入を安全にリトライする
POST /portal/keys/hourly は request_id を受け取ります。タイムアウト、接続の切断、409 mint_in_progress、5xx の後は、同じ request_id でリトライしてください。再利用した request_id で 2 本目のキーが作られたり課金されたりすることはありません。再送には already_issued: true とエイリアスが返ります。最初の結果がわかるまで、新しい ID を生成しないでください。詳しくは冪等性キーを参照してください。
トラブルシューティング
- チャージ直後の 401。 BroadNet のアカウントページには直近に記録された利用枠が表示され、入金の変更は反映中であることが示されます。ページを再読み込みし、反映が終わってから再試行してください。
- 毎分数リクエストしか送っていないのに 429。 4 リクエストの同時実行数の上限に当たっている可能性が高いです。たとえば長いストリームを並列で走らせている場合です。小さなワーカープールを使ってください。
- あるモデルでは 403 で、別のモデルでは通る。 キーのポリシーがそのモデルやルートを対象にしていません。たとえばプランのキーは
broadnet/deepseek-v4.1-flash用で、時間制キーはbroadnet/gemma-4-26b-a4bだけが対象です。 - SDK がリトライして二重に課金された。 リトライしたチャットのリクエストは新しい推論です。重複した回答のほうが失敗より高くつく場面では
max_retries=0にしてください。
サポートに送るもの
X-Request-ID ヘッダーの値、UTC のタイムスタンプ、ルート、HTTP ステータス、キーのエイリアスを添えてください。キーそのものは絶対に送らないでください。ヘッダーの読み方は OpenAI Python SDK のガイドで説明しています。
