API スロットリング

API スロットリングとは

API スロットリングは、API へのリクエスト数を一定の上限に制限し、サーバーの過負荷を防ぐトラフィック制御手法である。API Gateway がデフォルトでスロットリングを提供する。

スロットリング vs レートリミット

スロットリングとレートリミットの違いを以下にまとめる。

観点	スロットリング	レートリミット
超過時の動作	リクエストを遅延	リクエストを拒否 (429)
ユーザー体験	遅いが応答する	エラーが返る
実装	トークンバケット	カウンター

API Gateway のスロットリング

API Gateway のスロットリングを以下にまとめる。

設定	デフォルト
アカウント全体	10,000 req/秒
ステージ	10,000 req/秒
ルート	無制限 (ステージの上限まで)
バースト	5,000

トークンバケットアルゴリズム

トークンバケットアルゴリズムを図で示す。

バケット容量: 100 トークン
補充レート: 10 トークン/秒

リクエスト → トークンを 1 つ消費
トークンが 0 → 429 Too Many Requests

バースト: バケットが満タンなら 100 リクエストを一度に処理可能

クライアント側の対応

クライアント側の対応のコード例を示す。

// 429 を受けたら指数バックオフでリトライ
async function callApi(url: string, retries = 3): Promise<Response> {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url);
    if (res.status !== 429) return res;
    const delay = Math.min(1000 * 2 ** i, 30000);
    await new Promise(r => setTimeout(r, delay + Math.random() * 1000));
  }
  throw new Error('Rate limited');
}

スロットリングの設計指針

テナントごとに制限を設け、Usage Plan で API キーごとに上限を設定する。無料プランは 100 req/分、有料プランは 1000 req/分のように段階的な制限を設計し、429 レスポンスには Retry-After ヘッダーを含めてクライアントにリトライ時間を通知する。

現場での応用を知るには関連書籍も役立つ。