レート制限（Rate Limit）

レート制限かクォータか：どちらに当たったのかを見極める

どちらもリクエストの拒否として返ってきますし、両方に同じステータスコードを返すプロバイダーもあるため、エラーだけではどちらに当たったのか判断できないことがよくあります。対処の方向が正反対なので、コードに手を入れる前に切り分けておく価値があります。

• レート制限は、短い時間枠あたりのリクエスト数を数えます。対処は速度を落とすことです。リクエストの間隔を空け、キューに入れ、レスポンスに Retry-After ヘッダーがあればその時間だけ待ってから再試行します。
• クォータは、1日や1か月の利用総量（リクエスト、クレジット、メッセージ、トークン）を数えます。数秒待っても何も変わりません。選択肢はリセットを待つか、上限を引き上げるか、使う量を減らすかです。
• 同時実行数の制限は、どれだけゆっくり届くかに関係なく、同時に処理中にできるリクエスト数を制限します。処理を並列に展開したときに効いてきて、レート制限と取り違えやすいものです。

制限が何に対して数えられているかも確認してください。APIキーなのか、アカウントなのか、リクエストの送信元アドレスなのか。それによって、キーを1本増やして意味があるかどうかが決まります。

気づかないうちに使い切っていたクォータ

AgentCeres（agentceres.com の AI Growth Officer）は、作業中にウェブ検索を行うエージェントを運用しています。その検索は、無料プランのキー（月1,000クレジット）で検索APIを通していました。2026年9月、私たちのエージェント用コンテナの大半が共有していたキーが、1,000のうち1,002に達していることがわかりました。それらのワークスペースのウェブ検索はすべて失敗していたのに、どこにもその兆候は表示されていませんでした。エージェントは検索プロバイダーを直接呼び出していたため、そのトラフィックは私たちの側で数える仕組みを一切通っていなかったのです。

利用量の数字にも、覚えておく価値のある落とし穴がありました。上限で止まるカウンターが示すのは下限であって、測定値ではありません。キーを使い切ったあとは、以降の検索がカウントされずに失敗していたので、見えていた数字は実際の需要を下回っていました。余裕のあるキーに負荷を移したあと、上限に一切かからなかった丸1日のトラフィックは約153クレジット、月に換算すると約4,600になりました。キーが上限に張り付いていた間に見えていた月間利用量の、およそ4倍です。

2つ目の教訓は、確認用の仕組みを作る過程で得られました。プロバイダーの利用量エンドポイント自体にもレート制限があり、その制限はキーではなくリクエストの送信元アドレス単位で数えられていました。ひとつの確認で制限に触れた途端、5本の異なるキーがまとめて429を返したのです。キーごとに再試行するスクリプトなら状況を悪化させるだけだったので、私たちのスクリプトは最初の429で止まり、測定できなかったと報告します。そしてそれを、問題なしではなく失敗として扱います。

必ず当たる制限を前提に設計する

呼び出すサービスはいずれ必ず拒否してくると考え、それが製品の利用者にどう見えるかを前もって決めておきましょう。はっきりしたメッセージとして表に出る拒否は、少しの信頼を失うだけで済みます。気づかないうちに結果が悪くなる形で表に出る拒否は、はるかに高くつきます。直すべきものがあると誰も知らないからです。アプリがメールを送らなくなったのはなぜかでは、メール配信サービスで起きた同じ種類の障害を扱っています。そこでは拒否が別のエラーのような姿で返ってきました。

習慣は3つでほぼ足ります。レート制限に当たったら Retry-After に従って待ってから再試行する。ただし、決済や送信済みのメッセージのように、すでに実行された可能性がある操作は決して自動で再試行しない。従量課金のサービスは、実際に見る場所で利用量を記録し、上限に達したときではなく、かなり手前でアラートを出す。そして、測定値が取れないこと自体を警報として扱う。実行できない確認こそが、障害を隠しているからです。