429 は、トラフィックがレート制限を超えたことを意味します。毎分のリクエスト数、同時実行中のリクエスト数、毎分のトークン数、または支出のいずれかです。対処は 2 つに分かれます。上手にリトライする:上限付きの指数バックオフにランダムなジッターを加え、Retry-After に従います。一度に送る量を減らす:キーの同時実行上限に合わせたセマフォとキューを使います。どちらも下にコード付きで説明します。
ステータスコードの完全な一覧はエラーとリトライのガイドを、チェックポイントやタイムアウトを伴う数時間がかりのエージェント実行については長時間動くエージェント:タイムアウトとリトライを参照してください。
429 と 5xx の違いは?
| ステータス | 誰の問題か | リトライ? | 方法 |
|---|---|---|---|
| 429 | トラフィックが上限を超えた | はい | ジッター付きバックオフ。Retry-After に従う。同時実行数を下げる |
| 500 / 502 / 503 / 504 | サーバー側 | はい | 上限付きの指数バックオフ |
| 接続リセット、タイムアウト | ネットワークまたはサーバー | 通常は | バックオフ。ストリームの場合は再課金を許容できるときだけ |
| 400 / 422 | 不正なリクエスト | いいえ | ペイロードを修正 |
| 401 / 402 / 403 | キー、残高、ポリシー | いいえ | キーを修正、アカウントにチャージ、許可リストを修正 |
| 413 | リクエストが大きすぎる | いいえ | 小さくする |
BroadNet Inference では、429 はレート、同時実行、トークンレート、支出の 4 つのどの上限からも返る可能性があります。支出の上限は 30 秒では解除されません。BroadNet のドキュメントには、エラー本文のどのフィールドが上限の種類を示すのか書かれていないので、本文をログに残し、キーの詳細に表示される上限と照らし合わせてください。
オープンデータセット LLM API の無料枠とレート制限では、14 のプロバイダーが無料利用、初期のレート制限、カード登録の要否、無料枠データでの学習について公開している内容を比較しており、各値に出典と日付を付けています。
429 の原因になる上限は?
相手にしている数字を把握しておきましょう。BroadNet Inference では次のとおりです。
| キーの種類 | 毎分のリクエスト数 | 同時実行数 | その他 |
|---|---|---|---|
| 従量課金 | 30 | 4 | 共有の支出予算 |
| 時間制キー | 120 | 1 ストリーム | 毎分 300,000 トークン |
| 無制限プランのセッション | — | セッションごとに 1 リクエスト | トークンメーターなし |
LLM でいちばん重要なのは同時実行数です。ストリーミング回答は最後のトークンが届くまでスロットを占有するため、長い回答ほど、モデルが書き終えるまでの時間だけスロットがふさがります(BroadNet が示す標準的な速度は 毎秒約 100 トークン です)。キーのスロット数 4 を超える並列呼び出しを送ると、その 1 分間に送ったリクエストがわずかでも、超えた分は 429 になります。これは同時実行の問題で、バックオフだけではうまく対処できません。リリース前に上限に合わせてワーカー数を決めるには、無料の LLM レート制限計算ツールを使ってください。多数の項目からなる決まったジョブなら、LLM バッチジョブ計画ツールが同じ上限から実行時間を算出します。ほかのプロバイダーは数え方が異なります(毎分のトークン数、1 日のリクエスト数、同時実行数)。プロバイダー別の LLM API レート制限では、13 社を各社のドキュメントに基づいて比較しています。
ジッター付きバックオフはどう書くか?
素の指数バックオフは 1、2、4、8 秒と待ちます。100 のワーカーが同じ瞬間に制限されると、全員が同じ瞬間に戻ってきます。AWS が 100 の競合クライアントで行ったシミュレーションでは、フルジッターは呼び出し回数を半分以下に減らし、ジッターなしのバックオフより早く完了しました。もっとも単純なフルジッターは、ゼロから指数上限までのランダムな時間を待ちます。
import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
for attempt in range(max_attempts):
try:
return client.chat.completions.create(**kwargs)
except (RateLimitError, APIStatusError, APIConnectionError) as e:
status = getattr(e, "status_code", None)
if status is not None and status not in RETRYABLE:
raise # 400, 401, 403...: retrying will not help
if attempt == max_attempts - 1:
raise
retry_after = None
if getattr(e, "response", None) is not None:
retry_after = e.response.headers.get("retry-after")
wait = random.uniform(0, min(cap, base * 2 ** attempt))
if retry_after and retry_after.isdigit():
wait = max(wait, float(retry_after))
time.sleep(wait)
max_retries=0 は SDK 自身のリトライを無効にし、二重にリトライしないようにします。SDK の組み込みの挙動で十分なら、逆に自前のループをなくし、Python SDK ガイドのようにクライアントで max_retries=4 を設定する方法もあります。公式の Python と Node の SDK は、接続エラー、408、409、429、5xx をデフォルトで 2 回リトライします。
Retry-After は標準のヘッダー(RFC 9110)で、秒数か日付が入ります。BroadNet のドキュメントでは送信が約束されていないので、コードではオプションとして扱っています。
429 を未然に防ぐには?
同時実行中のリクエスト数を、キーの上限に抑えます。Python では、asyncio.Semaphore のオブジェクト 1 つと async with ブロック 1 つで実現できます。コードでは例として 4 を使っています。実際にはキーの同時実行上限(BroadNet の従量課金キーでは 4)に設定してください。
import asyncio, os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4) # match the key's in-flight limit
async def ask(prompt):
async with slots:
r = await client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main(prompts):
return await asyncio.gather(*(ask(p) for p in prompts))
results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))
gather はすべてのタスクを開始しますが、同時に動くのはセマフォが許可する数だけで、残りはセマフォの待ち行列で待機します。Node では、p-limit パッケージで同じことができます。ここでも 4 を例の値にしています。
// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";
const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit
async function ask(prompt) {
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: prompt }],
});
return r.choices[0].message.content;
}
const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));
毎分の上限にも対応するには、60 / rpm 秒ごとに 1 つ許可を出すトークンバケットを追加します。rpm はキーの毎分リクエスト上限です(BroadNet の従量課金キーでは 30)。
本格的なキューが必要になるのはいつか?
セマフォは 1 つのプロセスの中にしか存在しません。複数のワーカーやサーバーが 1 つのキーを共有すると、上限は共有されるのに、各プロセスには自分のトラフィックしか見えません。その場合は次のようにします。
- ジョブを共有キュー(Redis、SQS、データベースのテーブル)に入れます。
- キーの同時実行上限と同じ数のコンシューマーを固定で動かします。
- 各ジョブに ID を付けて結果を ID ごとに保存し、リトライしたジョブが二重に実行されないようにします。
- 対話型のトラフィックとバッチのトラフィックは別のキーか別のキューに分け、バッチの滞留が返答を待つユーザーを妨げないようにします。
Batch API なしで数千項目を処理する一括ジョブについては、再開可能なバッチランナーを参照してください。
429 を障害に変えてしまうリトライのミスは?
- **上限のないリトライ。**長い障害の間に上限のないリトライループが回ると、負荷が何倍にもなり、トークン課金では請求額も膨らみます。
- **途中まで進んだストリームをやみくもにリトライする。**ストリームがすでにトークンを返していた場合、リトライはまったく新しい推論になり、ユーザーには文章が二重に表示されるかもしれません。不完全なストリームの検出方法はストリーミングの記事を参照してください。
- **アカウントのエラーをリトライする。**従量課金の利用枠を使い切ったときの 401 や、残高不足の 402 は、自然には解消しません。
すべてのリトライを、ステータス、待ち時間、レスポンスヘッダー X-Request-ID とともに記録してください。BroadNet のドキュメントは、サポート用にこのヘッダーを保存するよう求めています。リトライ率の上昇は、容量が足りなくなっていることを示すいちばん早い兆候です。記録の方法は使用量ログで紹介しています。
BroadNet Inference が向いているケース
BroadNet の上限は公開されており、それを前提に設計できる程度に小さい値です。従量課金キーでは同時実行 4 リクエストです。アプリやエージェントには十分ですが、1 つのキーで数百の並列呼び出しをしたい一括ジョブには窮屈です。エージェント向けには、無制限プランにトークンメーターがなく、セッションごとに同時に 1 リクエストを実行します。並列で作業するにはセッションを増やします。詳しくはコーディングエージェントの並列実行を参照してください。最新の上限は API リファレンスにあります。
