自社APIの上限は誰を守るか。レート制限の単位・同時実行・伝え方を分けて設計する

編集部の実務提案

制限は誰を守るのかを先に決める

レート制限の目的は1つではない。自社のインフラ容量を守ること、利用者間の公平さを保つこと、悪用や総当たりを抑えること、コストの高い処理の消費を抑えること。どの目的を主とするかで、上限の単位も値も変わる。目的が曖昧なまま「とりあえず秒間100回」と置くと、守りたいものを守れず、止めなくてよいものまで止める制限が残る。

Stripeの設計は目的の分離が分かりやすい。リクエスト数の制限はアカウントごとに秒単位で測られ、全体の上限と個別エンドポイントの上限が併用される。同時に、処理に時間のかかるリクエストについては同時実行数という別の物差しが用意されている。流量と占有時間を別々に縛ることで、短いリクエストの洪水と、重いリクエストの滞留を、それぞれ独立に防いでいる。

GitHubの設計は時間軸が違う。認証済み利用者には1時間あたり5,000リクエストという一次制限があり、その内側に同時実行や生成系リクエストへの二次制限が重なる。バーストを秒で均す設計と、総量を時間で管理する設計は、想定する利用パターンが違う。自社のAPIがどちらの性格を持つか、短時間の集中が怖いのか、総量の膨張が怖いのかを言語化することが先決である。

制限値を決める材料は実測である。現在の利用分布、上位の利用者のパターン、処理ごとのコスト。制限は「通常の利用の少し上」に置くのが原則で、実測なしに決めた値は、正当な利用をはじくか、守れないほど緩いかのどちらかになる。公開前に利用状況の分布を取り、上限の初期値を根拠付きで置く。

そして制限は、設けた瞬間から利用者との契約になる。上限を超えたときに何が返るか、どう伝え、どうすれば解消できるかまで含めて仕様である。制限そのものより、制限に触れたときの体験が、APIの評価を左右する局面は多い。

目的の言語化には、利用者への説明責任の側面もある。制限に触れた利用者から「なぜ止められたのか」と問われたとき、容量保護なのか、公平さなのか、コストなのかが即答できる状態は、サポートの品質そのものである。目的が社内で共有されていない制限は、問い合わせのたびに現場の解釈で答えることになり、回答がぶれる。制限値は数字であると同時に、説明の台本でもある。

なお、内部利用と外部利用で目的が衝突することもある。自社のバッチ処理が容量を使い切り、外部の利用者を締め出すような事態は、統制の欠如である。内部利用者にも同じ上限の規律を適用するか、内部用の枠を分けて容量計画に織り込むか。提供側の設計は、社内システムも「利用者」として数えるところから始まる。

出典：[1][2]

編集部の実務提案

上限の単位を分ける。全体・エンドポイント・リソース

上限の単位は、少なくとも3層に分けられる。アカウント全体の上限、エンドポイントごとの上限、そして特定リソースに対する上限である。全体の上限は総量の暴走を防ぎ、エンドポイント別の上限は重い処理を守り、リソース別の上限はホットな対象への集中を抑える。1層だけでは、どれかの脅威に無防備になる。

Stripeでは、ライブモードの全体上限が秒間100リクエスト、個別エンドポイントは一般に秒間25リクエストとされ、さらにリソース固有の制限も存在する理由コードから読み取れる。エンドポイントごとにコストが違う以上、上限も一律である理由はない。決済の作成と参照では、必要な保護が違う。

単位の選択は、課金や契約の単位とも関係する。アカウント単位の上限は、契約主体ごとの公平さを担保しやすい。一方、同じアカウントから複数システムが使う構成では、1つのシステムの暴走が他のシステムを巻き込む。APIキー単位や用途単位の細分化は、巻き込みを防ぐ代わりに、管理と説明のコストを増やす。どこまで細かくするかは、利用者の実態に合わせて決める。

上限の測り方にも設計が要る。固定ウィンドウ、スライディングウィンドウ、トークンバケットでは、境界付近の挙動が変わる。秒単位の制限ではバーストの許容度が体験を左右し、時間単位の制限では回復までの待ち時間が問題になる。測定方式と回復方式はセットで決め、利用者に説明できる形にしておく。

単位と値の一覧は、内部資料ではなく公開ドキュメントに載せるべき情報である。利用者は上限を知って初めて、自前の再試行や流量制御を設計できる。伏せられた上限は、利用者にとって「理由の分からない失敗」と同じである。

リソース単位の制限は、人気コンテンツを持つAPIで特に効く。特定の対象への読み取りや書き込みが集中すると、全体の流量は平常でも、その対象を保持するデータストアだけが悲鳴を上げる。対象ごとの同時実行や頻度を縛る設計は、全体制限の数字を下げることなく局所的な過熱を冷ます。ホットスポットの検知とセットで設計したい。

プラン別の上限も単位設計の一部である。無料枠と有料枠で値を変えるのは一般的だが、値の差だけでなく、引き上げの速度やサポートの範囲といった運用面の差も含めて設計する。制限値は価格表の一部であり、製品設計の言葉で語れる必要がある。技術部門だけで決めた制限は、営業やサポートの現場で説明できない数字になりがちだ。

出典：[1][2]

編集部の実務提案

レートと同時実行数は別の制限である

見落とされやすいのが、リクエストの「頻度」と「同時実行数」は別物だという点である。頻度が低くても、1件の処理が長ければ同時実行は積み上がる。逆に、短いリクエストなら高頻度でも占有は小さい。両方を1つの数字で縛ると、どちらか一方の脅威に過剰か過小になる。

Stripeはこの分離を明示している。同時実行数の制限はレート制限とは別であり、ライブモードの全体の既定は50件の処理中リクエストとされる。超過時には理由コードで同時実行由来であることが返されるため、利用者は「速く送りすぎ」なのか「長く抱えすぎ」なのかを区別できる。原因の区別ができることは、是正の速さに直結する。

GitHubの二次制限にも同時実行の考え方がある。同時リクエストは最大100までとされ、点数制の制限や、コンテンツ生成系への分・時間の上限と組み合わさる。重い処理を点数で重み付けする方式は、処理コストの差を制限に反映させるもう一つの答えである。

自社APIに引き直すと、設計手順はこうなる。まず処理を棚卸しし、平均と上限の所要時間を測る。時間が支配的な処理には同時実行数の制限を、件数が支配的な処理にはレートの制限を、両方が効く処理には両方を設定する。インメモリの待ち行列やデータベース接続のような、裏側の有限資源へのマッピングまで書けると、制限値は恣意的な数字ではなく容量計画の表現になる。

同時実行の制限は、利用者の並列バッチ処理と相性が問題になりやすい。大規模な一括処理を行う利用者には、非同期のジョブ型APIや一括エンドポイントを用意することが、本質的な回避策になる。同期APIの上限だけで大量処理の需要を受け止めようとすると、制限は常に摩擦を生む。

同時実行数の制御は、タイムアウト設計とも連動する。同時実行の枠が処理時間の長いリクエストで埋まると、後続は待たされ、やがてタイムアウトする。利用者側のタイムアウトが自社の制限より短ければ、利用者は結果の分からないリクエストを再試行し、同時実行をさらに圧迫する悪循環が生まれる。制限値、処理時間の上限、推奨タイムアウトは、3点セットで公開するのが望ましい。

キューイングを挟むかどうかも判断点である。枠が空くまで短時間待たせる設計は、瞬間的な集中を吸収できる反面、応答時間のばらつきを生む。即座に429を返す設計は、利用者に制御を委ねる代わりに、再試行の設計を利用者任せにする。どちらが利用者の実装と相性がよいかは、APIの用途次第である。少なくとも、待たせるのか弾くのかの方針は明示したい。

出典：[1][2]

編集部の実務提案

伝え方が仕様になる。ヘッダー・理由・再試行指示

制限に触れたときの応答は、仕様の中核である。HTTPの429を返すだけでは、利用者は何が起きたか分からない。制限の種類、上限、残量、回復時刻、再試行してよいか。これらをヘッダーと本文で機械可読に返すことが、利用者の自動回復を可能にする。

GitHubは残量の開示が徹底している。x-ratelimit-limit、remaining、used、reset、resourceというヘッダーで、上限と消費と回復時刻が分かり、利用者は使い切る前に自制できる。このヘッダーこそが正確な情報源であると明記されている点も重要で、文書の記述より実行時の値を正とする姿勢が、利用者の実装を安定させる。

Stripeは理由の開示に特徴がある。429応答のStripe-Rate-Limited-Reasonヘッダーは、全体レート、エンドポイントレート、全体同時実行、エンドポイント同時実行、リソース固有のいずれで制限されたかを示す。さらに注意すべきは、理由ヘッダーのない429はレート制限ではなく、ロックのタイムアウトなど別の要因であり得るという点である。同じ429でも原因が違えば対処が違う。理由を返すことは、誤った対処の連鎖を断つ。

回復の指示も含める。二次制限ではretry-afterヘッダーで待機時間が示される。再試行可能な時刻が分からなければ、利用者は推測で叩き続け、制限を長引かせる。待つべき時間を示すことは、利用者のためであると同時に、自社の負荷を下げる行為でもある。

エラーの本文には、人間向けの説明と、恒常的な対処への案内を併記する。上限引き上げの申請先、利用状況の確認方法、想定を超える使い方をしている場合の相談窓口。制限に触れた瞬間は、利用者が最も案内を必要としている瞬間である。その瞬間の設計が雑だと、APIへの不信は静かに蓄積する。

出典：[2][1]

編集部の実務提案

公平さの設計と悪用への対応は分ける

通常の利用者の公平さと、悪用の抑止は、別の設計である。公平さは契約単位の上限と実測に基づく値で担保する。悪用は、認証なしアクセスの強い制限、キー漏洩時の遮断、異常なパターンの検知といった別の道具で扱う。悪用対策の厳しさを通常利用の上限に混ぜると、正当な利用者が割を食う。

認証の有無で上限が大きく変わるのは各社共通である。GitHubでは未認証はIPあたり1時間60リクエストまでと低く、認証済みは5,000まで開かれる。身元の分かる利用者には広く、匿名には狭く。この非対称は、制限の設計における基本形の一つである。

適応型の制限も選択肢になる。Stripeの不正対策では、攻撃の検知に応じて制限を動的に強化する仕組みが語られている。平時の上限は利用体験のために緩く保ち、異常検知時にだけ締める。ただし動的な変更は説明可能性を下げるため、発動条件と解除条件、利用者への通知方針を先に決めておく必要がある。

キー単位の遮断や制限の即時変更は、運用手順として整備する。キーの漏洩や暴走が起きたとき、誰が、どの権限で、どれだけの時間で制限を切り替えられるか。制限の設計は、値の設計であると同時に、緊急時の操作設計でもある。手順がなければ、設計した制限は緊急時に機能しない。

公平さの検証も要る。上限が特定の利用形態だけを不当に締め付けていないか、大口利用者の正当なピークを誤って弾いていないか。制限に触れたリクエストの内訳を定期的にレビューし、誤検知の割合を把握する。制限は設けて終わりではなく、当たり方の監査が運用の一部である。

漏洩したキーの扱いは、制限と認証の境界にある。キーの失効は最終手段で、業務が止まる。制限を一時的に強める、特定の送信元だけを止めるといった段階的な対応が用意されていると、被害の拡大を防ぎながら利用者と連携して切り替えられる。緊急対応の階段を、平時の設計に組み込んでおくことが大切である。

また、制限の回避を試みる利用者への対応方針も決めておく。アカウントの量産やキー分散で上限を逃れる行為は、利用規約との関係で判断が要る領域である。技術的な検知と、規約に基づく措置、警告から停止までの段階。これらをアドホックに決めると、措置の一貫性が問われる。制限は技術であると同時に、サービス運営の規律でもある。

出典：[2][1]

編集部の実務提案

引き上げ・変更・予告という利用者との運用

上限は固定ではない。正当な利用の成長に合わせて引き上げる経路を用意する。申請の窓口、審査の観点、回答までの目安。引き上げの経路がなければ、利用者はキー分散のような回避策に流れ、実態の把握が難しくなる。引き上げを正規の手続きとして設計することは、統制のためにも必要である。

ビジネスの繁忙期のような予見可能なピークには、一時的な引き上げの相談に応じる運用も考えられる。決済やメディアのように季節性の強い領域では、ピークに合わせた上限の調整が、障害と機会損失の両方を減らす。申請期限と必要情報を明示すれば、利用者側も計画に組み込める。

制限の変更、特に引き下げや測定方式の変更は、破壊的変更として扱う。事前告知、移行期間、変更後の値の公開。黙って締めると、利用者の本番で突然の失敗が増え、原因究明の問い合わせが殺到する。変更の影響範囲を、制限に触れている利用者の実績から洗い出して告知先を決める。

利用状況の可視化も提供側の仕事である。利用者が自らの消費量と上限への接近を確認できるダッシュボードやAPIがあると、制限に触れる前に自制や増量申請ができる。GitHubが制限状況の取得手段を用意しているように、消費の見える化は、制限の摩擦を下げる最も安い方法の一つである。

サポートとの連携も設計に含める。制限に関する問い合わせでは、利用者の消費実績と制限の内訳をすぐ引けることが対応速度を決める。理由コードの設計は、利用者の自己解決のためだけでなく、サポートの切り分けのための投資でもある。

告知の実務では、変更をコードの都合で決めないことも重要である。利用者の繁忙期や決算期に制限変更を重ねると、影響の切り分けが困難になる。変更カレンダーは利用者の業務カレンダーと照らして引く。提供側のリリース都合だけで日程を決める癖は、制限以外の変更についても同じ問題を起こす。

ドキュメントには、制限の「現在値」だけでなく履歴も残したい。いつ、どの値を、なぜ変えたか。利用者は自システムの障害調査で、過去のある時点の制限値を必要とすることがある。変更履歴の公開は、その調査を可能にし、提供側への問い合わせ自体を減らす。透明性はサポートコストの削減策でもある。

出典：[1][2]

編集部の実務提案

制限はテストし、文書化し、監査する

制限の実装はテスト対象である。上限の境界で正しく429が返るか、理由コードが原因と一致するか、回復時刻の計算が正しいか、制限が特定の経路で抜けていないか。本番で初めて制限の挙動を確認する事態は避けたい。負荷試験のシナリオに、制限の発動と回復を含める。

文書化では、値の一覧だけでなく、単位、測定方式、回復方式、理由コードの意味、引き上げ手続きまでを公開する。バージョンや契約プランで値が違う場合は、その差異も明示する。文書と実際の挙動の乖離は、利用者の実装を静かに壊す。挙動を変えたら文書も同じ変更に含める運用が要る。

制限に触れたリクエストの記録は、監査と改善の材料である。どの利用者が、どの制限に、どれだけ触れているか。恒常的に上限に張り付く利用者は、引き上げの提案先であり、同時に容量計画の入力でもある。制限のログは、拒否の記録ではなく需要の記録として読む。

自社内のドッグフーディングも有効である。自社の他システムや監視が同じAPIを使うなら、その消費を通常利用の代表として観察できる。制限が自社の正当な利用をはじくなら、外部の利用者も同じ目に遭っているはずである。内部利用者の不満は、制限設計の無料の監査である。

まとめると、提供側のレート制限は、単位、同時実行、伝達、公平、運用、検証の設計の束である。上限の数字だけを決めて終わる仕事ではない。制限に触れた利用者が、理由を理解し、回復でき、必要なら相談できる。その状態まで作れて初めて、制限は安定性のための仕組みとして完成する。

制限のテストでは、利用者代表としての検証も価値がある。主要なSDKや利用パターンで、制限に触れたときに期待通りに回復できるかを確かめる。理由コードの解釈ミスや、ヘッダーの読み落としは、利用者の実装で頻出する。提供側が代表的なクライアント実装で検証しておくと、文書の曖昧さにも早く気づける。

最後に、制限の値そのものを定期レビューの対象にする。利用実態は変わり、処理コストも最適化で下がる。公開当初の値を聖域化せず、実測の分布が動いたら値も動かす。制限は一度決めたら不変のものではなく、容量計画と利用実態の変化に追随させる運用物である。その姿勢が、制限を「邪魔な壁」から「信頼できる約束」に変える。

出典：[1][2]