APIレートリミットの仕組み — 429が出たら何を確認する？

ひよこ

商品検索APIを何度も呼んだら、429って返ってきたよ。

ペンギン先生

決められた時間内の呼び出し量を制限するレートリミットに達したのかもしれないね。まず応答とAPIの規約を確認しよう。下では「同じ60秒枠で3回まで」という小さな例から見るよ。

ひよこ

えー、なんでわざわざ制限するの？たくさん使わせてくれればいいのに！

ペンギン先生

気持ちは分かるけど、制限がないと大変なことになるよ。たとえば1人のユーザーが毎秒1万回リクエストを送ったら、処理能力を超えると他のユーザーも使えなくなるおそれがある。レートリミットには主に3つの目的があるんだ。サーバーの保護、ユーザー間の公平性の確保、そしてDDoS攻撃のような悪意あるアクセスへの防御だね。

ひよこ

なるほど、みんなが快適に使えるようにするための仕組みなんだね！具体的にはどうやって回数を数えてるの？

ペンギン先生

一番シンプルなのは「固定ウィンドウ方式」だよ。たとえば「1分間に100回まで」というルールなら、毎分00秒にカウンターをゼロにリセットして、リクエストが来るたびに1を足していく。100回までは受け付け、101回目から次のリセットまで拒否するんだ。実装が簡単だから広く使われてるよ。

ひよこ

シンプルでいいね！でも何か弱点とかあるの？

ペンギン先生

いいところに気づいたね。固定ウィンドウには「境界問題」があるんだ。たとえば0:59に100回、1:00にまた100回リクエストを送ると、実質2秒間に200回のアクセスが集中しちゃう。これを解決するのが「スライディングウィンドウ方式」で、直近の時間窓を見て判定するんだ。個々の時刻を厳密に記録する方式ならこの例の集中を防げるけれど、時間を区間に分けて近似する実装もあるので、精度と計算量に違いがあるよ。

ひよこ

スライディングウィンドウのほうが賢いんだね！他にも方式ってあるの？

ペンギン先生

有名なのが「トークンバケット方式」だよ。バケツの中にトークン（許可証）が入っていて、リクエストを送るたびにトークンを1つ消費する。トークンは一定のペース、たとえば1秒に10個ずつ自動で補充されるんだ。バケツが空になったらリクエストは拒否されるけど、バケツには容量の上限があり、貯まったトークンの範囲でバーストも許容される。平均的な流量を制限しつつ、一時的な集中は柔軟に受け入れてくれるバランスのいい方式だね。

ひよこ

トークンが貯まってれば一気に使えるのは便利だね！ところで、あとどれくらいリクエストできるかってどうやって知るの？

ペンギン先生

APIによってはHTTPレスポンスヘッダーで教えてくれるよ。たとえばGitHubのREST APIでは、X-RateLimit-Limitが上限回数、X-RateLimit-Remainingが残り回数、X-RateLimit-Resetがリセットされる時刻だね。ただしヘッダー名や単位はAPIごとに違うし、別の二次制限もある。残り回数だけで次の成功を保証するものではないよ。

ひよこ

それでも429エラーが出ちゃったときはどうすればいいの？

ペンギン先生

そのときは「指数バックオフ」でリトライするのも方法の1つだよ。1回目のリトライは1秒後、2回目は2秒後、3回目は4秒後…と待ち時間を倍々に増やしていく方法だね。Retry-Afterは待機する秒数またはHTTP日時なので、その値とAPIの再試行規約に従おう。再試行回数には上限を設け、待ち時間にランダムなずれを入れると一斉再試行を減らせるよ。絶対にやってはいけないのは、429が返ってきたのに即座にリトライし続けること。サーバーにさらに負荷をかけてしまって、状況が悪化するだけだよ。

ひよこ

倍々に待つのは賢いやり方なんだね！レートリミットってアプリのコードで実装するものなの？

ペンギン先生

自分で実装することもできるけど、最近はAPI GatewayやCDNの機能として提供されることが多いよ。たとえばAWSのAPI Gatewayなら、レートとバースト容量を設定できる。ただし上限はベストエフォートの目標値で、厳密な最大回数の保証ではないよ。エッジ側に制限を置けば、条件に合うリクエストをサーバーへ転送する前に止める設計もできるよ。レートリミットだけですべてのDDoSを防げるわけではないんだ。大規模なサービスでは、ユーザーごと・APIキーごと・IPアドレスごとに別々の制限を設けたりもするよ。

まずは、商品検索を4回続けて呼ぶ場面を見る

レートリミットは、決めた時間内の呼び出し量を制限する仕組みです。商品を検索するAPIへ、同じ利用者から連続で4回アクセスするとします。

「同じ固定の60秒枠で3回まで」という練習用のルールなら、次のように判定できます。実際のサービスの制限値ではありません。

HTTPでは、制限に達したことを429 Too Many Requestsで伝える方法があります。ただし、429を必ず返すとは限らず、負荷や設計によって接続を拒否する場合もあります。誰を同じ利用者として数えるか、APIごとか全体かは、サービスの規約を確認します。

429が返ったら、まず応答と規約を読む

次は説明用の応答の一部です。

HTTP/1.1 429 Too Many Requests
Retry-After: 30

このRetry-Afterは、応答を受けてから30秒待つ指定です。HTTP日時で示される場合もあります。必ず付いているヘッダーではないので、APIの再試行手順も確認してください。

1. 同じリクエストを送り続ける処理を止める。
2. Retry-AfterやAPIの制限・再試行規約を確認する。
3. 再試行できる処理か確かめ、回数と待ち時間に上限を付ける。
4. 改善しなければ、呼び出し回数や並列数、キャッシュを見直す。

読み取りと注文・決済では、再試行の意味も違います。結果が分からない書き込みを繰り返す場合は、二重処理を防ぐ設計が必要です。

窓の境目と、トークンの補充は別の方式

固定ウィンドウでは、同じ枠の上限内であれば、終わり際と次の枠の始めに呼び出しが集中し得ます。例えば各枠3回なら、境目をまたぐ短時間に合計6回を受け付けることがあります。「任意の直近60秒でも必ず3回」ではありません。

スライディングウィンドウには、個々の時刻を追う方式や、区間ごとに近似する方式があります。トークンバケットでは、上限まで許可証を貯め、決めたペースで補充して消費します。貯まった分の一時的な集中は許せますが、補充で容量を超えて増やし続けるわけではありません。

図のトークン3枚は仕組みを見るための例です。1回につき1枚なら、同時点で4回目を送る前に補充がなければ、許可証が足りません。

運用では「数える単位」も確かめる

IP単位では、同じネットワークの複数利用者が枠を共有する場合があります。利用者やAPIキー単位なら、認証の扱いを確認します。複数サーバーで別々に数える実装は、サービス全体の厳密な上限にならないこともあります。

GitHubのX-RateLimit-Remainingなどの値は判断材料ですが、一次制限とは別の制限もあり、残数があるから次の成功を保証するものではありません。AWS API Gatewayの上限もベストエフォートの目標値です。レートリミットだけで、すべてのDDoS攻撃を防げるわけでもありません。

覚え方と次の一歩

「レートリミット」って出てきたら「一定の時間に受け付ける量の制限」と思えばだいたいOK！

次はAPI開発入門で応答を確認し、サーキットブレーカーと、量を制限する仕組み・障害時に遮断する仕組みを比べられます。

参考資料

• RFC 9110 section 10.2.3 — Retry-Afterは秒数またはHTTP日時。
• GitHub REST API rate limits — 未認証は送信元IP単位60/時、認証ユーザーは通常5000/時。検索・二次制限・認証方式などの例外。
• AWS API Gateway throttling — トークン補充速度・容量、上限はベストエフォート。
• ASP.NET Core rate limiting — スライディングの区間分割実装と容量を超えないトークン補充。
• RFC 6585：429 Too Many Requests — 429の意味とRetry-After、識別単位と数え方はサービス次第