APIレートリミット計算

APIレートリミットは、サードパーティサービスと連携する際にすべての開発者が直面する基本的な制約です。決済ゲートウェイ、機械学習推論API、ソーシャルメディアプラットフォームなど、どのサービスを利用する場合でも、プロバイダーは一定の時間ウィンドウ内で送信可能なリクエスト数に上限を設けています。この上限を超えると、通常はHTTP 429（Too Many Requests）レスポンスが返され、一時的なブロックやアカウント停止につながることもあります。プロジェクトの初期段階からレートリミットを考慮した設計を行うことで、後々のコストのかかるリファクタリングを避けることができます。

レートリミットの仕組み

レートリミットは、リクエスト数と時間ウィンドウの2つの要素で構成されます。一般的な例として「1分間に100リクエスト」があり、これはサーバーがローリング60秒間に最大100回の呼び出しを許可することを意味します。プロバイダーによっては、時計の境界（例：毎分0秒）でリセットされる固定ウィンドウを使用する場合と、各リクエストの直前60秒間を追跡するスライディングウィンドウを使用する場合があります。この違いは重要です。固定ウィンドウでは境界付近でバーストリクエストを送ることが可能ですが、スライディングウィンドウはより均一な制御が可能な一方、動作の予測が難しくなります。

多くのAPIは複数の階層のリミットを同時に設けています。例えば、「1秒あたり10リクエスト、かつ1時間あたり1,000リクエスト、かつ1日あたり10,000リクエスト」といった具合です。アプリケーションはすべての階層を同時に遵守する必要があるため、使用パターンに対して最も制約の厳しいリミットに合わせて計画する必要があります。

共通の単位への正規化

異なるプロバイダー間でリミットを比較したり、1日あたりの合計キャパシティを計画するには、すべてのリミットを「秒あたりのリクエスト数」に変換すると便利です。1分あたり100リクエストの制限は、約1.67リクエスト/秒に相当します。1時間あたり5,000リクエストの制限は、約1.39リクエスト/秒です。この計算ツールはこの変換を自動的に行い、分あたり、時間あたり、日あたりの数値にも換算するため、全体像を一目で把握できます。

1日あたりのリクエスト予算がわかれば、アプリケーションが1回の論理操作で発行するAPI呼び出し回数で割ることで、リミットが許容する完全な操作数を求められます。例えば、ユーザー検索1回につき4回のAPI呼び出しが発生し、1日のリクエスト予算が10,000件の場合、制限内で実行できる検索は1日2,500回です。

リクエスト間の推奨遅延時間

レートリミットを超えないための最もシンプルな方法は、連続するリクエスト間に最小遅延を設けることです。制限が1分間に100リクエストの場合、安全な最小間隔は60,000ミリ秒÷100＝600ミリ秒です。この計算ツールでは、その最小値に5%の安全マージンを加え、この例では630ミリ秒を算出します。このマージンは、わずかな時計のずれ、ネットワークジッター、およびほとんどのプロバイダーがウィンドウをミリ秒単位の整数で計測するという事実を考慮しています。

固定遅延は、逐次的なシングルスレッドワークフローに適しています。並列または同時実行のワークロードでは、トークンバケットやリーキーバケットアルゴリズムがより適切です。これらはウィンドウサイズまでのバーストを許容しつつ、時間経過に対する平均レートを維持します。Bottleneck（Node.js）やratelimit（Python）などのライブラリがこれらのパターンを実装しています。

1日のリミット到達までの時間

予想される操作率が1日のリクエスト予算を深夜までに消費してしまう場合、この計算ツールはその到達時点までの所要時間を表示します。例えば、1日のリミットが1,000リクエストで、各操作に5リクエストが必要な場合、予算は200操作分です。1日に300操作を予定している場合、リミットを超過することになり、計算ツールは推定到達時間を表示します。

到達時間を把握することで、操作を1日を通じて均等に分散させるか、高価値の操作を優先的に早い時間帯に実行するか、あるいはプロバイダーとより上位のプランを交渉するかを判断できます。

バーストキャパシティ

バーストキャパシティとは、リミットが発動するまでに単一のウィンドウ内で送信できるリクエストの最大数を指します。1分間に100リクエストの制限では、バーストキャパシティは100です。これはバッチ処理で有用です。80件のレコードを一括インポートする必要があり、それぞれ1回のAPI呼び出しが必要な場合、48秒かけて分散させるのではなく、80件すべてを一度に送信してもバーストキャパシティの範囲内に収まります。

プロバイダーによっては、静かな期間にトークンが蓄積された場合、名目上のレートを一時的に超えるバーストを許容するトークンバケットアルゴリズムを実装している場合があります。そのようなケースでは、バースト上限がここに表示されるウィンドウ制限よりも高くなる可能性があります。具体的なバースト仕様については、必ずプロバイダーのドキュメントを確認してください。

実践的な戦略

APIレスポンスのキャッシュは、繰り返しのクエリに対するリクエスト数を削減します。同じデータが短期間に複数回リクエストされる場合、ローカルキャッシュから提供することで冗長なAPI呼び出しを回避できます。キャッシュの無効化ロジックは、ユースケースに応じたデータの鮮度の許容範囲に合わせて設定する必要があります。

レートリミットに達した場合の標準的なリトライ戦略は、ジッター付きの指数バックオフです。429レスポンスを受信したら、基本遅延（例：1秒）で待機し、その後の失敗ごとに待機時間を倍増させ、複数のクライアントが同時にリトライする「サンダリングハード」効果を避けるためにランダムなジッターを加えます。ほとんどのクラウドSDKはこのパターンを自動的に実装していますが、リトライ設定を確認しておくことをお勧めします。

リクエストバッチ処理——複数の論理操作を1回のAPI呼び出しにまとめる方法——は、多くのAPI（GraphQL、Stripe など）でサポートされています。APIがバッチ処理をサポートしている場合、実際のHTTPリクエスト数を大幅に削減でき、バッチサイズに等しい係数で実効レートリミットを引き延ばすことができます。