BroadRouter
始める

BroadNet Inference のエラーコードとリトライすべき場合

更新日

ボディをパースする前に HTTP ステータスを確認してください。429 と 5xx は、上限を設けた指数バックオフでリトライします。400、403、413、422 はリトライ前に修正が必要です。401 はキーと残高を、402 はアカウントへの入金を確認してください。サポート用に X-Request-ID ヘッダーは必ずログに残してください。

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 のガイドで説明しています。

よくある質問

LLM API の 429 エラーはリトライすべきですか?

はい。上限を設けた指数バックオフでリトライしてください。BroadNet Inference の 429 は、レート、同時実行数、トークンレート、または支出の上限に達したことを意味します。頻発するなら並列度を下げ、原因が支出の上限ならリトライをやめてください。

キーは正しいのに 401 になるのはなぜですか?

BroadNet の 401 は、キーの誤りや期限切れだけでなく、従量課金の利用枠の使い切りや予算のブロックも含みます。アカウントページで残高とキーの状態を確認してください。

ここでの 401 と 403 の違いは何ですか?

401 はキーかアカウントの利用枠の問題です。403 はキーは有効でも、モデル、ルート、IP のポリシーでリクエストが拒否されたことを意味します。たとえば許可リストにないアドレスからの呼び出しです。

OpenAI SDK はエラーを自動でリトライしますか?

はい。OpenAI Python SDK は、接続エラー、408、409、429、5xx をデフォルトで 2 回、短い指数バックオフでリトライします。回数を変えるには max_retries を設定し、0 にするとリトライしなくなります。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く