API レート制限とは
API レート制限は、定められた期間またはリソース使用枠内でクライアントが送信できるリクエストを制限します。サービスは、アカウント、認証情報、エンドポイント、アドレスなどの使用範囲ごとに制限を適用できます。
API レート制限の仕組み
レートリミッターは、アカウント、認証情報、IP アドレス、エンドポイントなどの区分に割り当てられたクォータに対し、リクエスト数またはリクエストごとの重み付きコストを計上します。同じリクエストに複数のポリシーが適用されることもあります。バーストの扱いは、カウントのアルゴリズムによって決まります。固定ウィンドウカウンターは各ウィンドウの境界でリセットされるため、クライアントはリセットの直前にそのウィンドウのクォータを、直後に次のウィンドウのクォータを使い切れます。スライディングウィンドウは、この境界での急変をなだらかにします。たとえば、前のウィンドウのカウントに、現在も重なっている部分の割合に応じた重みを付けて加算します。トークンバケットは、一定の容量を上限に、一定の速度でトークンを追加します。この容量が、許容するバーストの上限になります。リーキーバケットは一定の速度で排出します。NGINX の実装では、デフォルトで超過リクエストを遅延させ、設定されたバーストサイズを超えると拒否します。サービスは、リクエストレート、同時リクエスト数の上限、高コストな操作やコンテンツを作成する操作用の別枠など、複数のリミッターを並行して運用できます。そのため、ある制限を下回っていても、すべての制限を下回っているとは限りません。リクエストを拒否する際、レスポンスで待機時間を示すことができます。これにより、クライアントは一斉に再試行するのではなく、再試行のタイミングを分散できます。
要点
- HTTP は、レート制限されたリクエストに対してステータス 429 Too Many Requests を定義しており、レスポンスには
Retry-Afterヘッダーが含まれることもありますが、どちらも保証されません。GitHub のドキュメントでは、403 または 429 を返し、値が 0 のx-ratelimit-remainingヘッダー、またはレート制限の超過を示すエラーメッセージを添える場合があるとされています。NGINX のlimit_reqモジュールは、limit_req_statusが設定されていない限り、503 で拒否します。429 だけで判断せず、API のドキュメントに記載されたステータスコード、ヘッダー、エラー本文からスロットリングを検出してください。 Retry-Afterは、レスポンス受信後に待機する秒数、または HTTP 日付のいずれかなので、クライアントは両方の形式を解析する必要があります。待機時間を別の場所で示す API もあります。GitHub は、UTC のエポック秒で表す時刻であるx-ratelimit-resetも使用し、ほかのサービスでは JSON のエラー本文に待機時間を含めます。API のドキュメントで指定された場所と単位で待機時間を読み取ってください。- 残りのクォータを通知するための標準は、まだ完成していません。
RateLimitとRateLimit-Policyのヘッダーフィールドは、IETF Internet-Draft(2026 年 5月付、改訂 11 )であり、RFC ではありません。運用中の API は、x-ratelimit-remainingなどのベンダー固有の名前を使用しています。このドラフトは、通知されたクォータを保証と見なさないようクライアントに求めており、レスポンスに両方が含まれる場合はRetry-Afterを優先するとしています。 - 多数のサーバーにまたがるリミッターはカウンターを共有したり近似したりするため、通知されるクォータは正確とは限りません。GitHub は、複数のリージョンでリクエストを処理すると、レスポンスごとに残りのカウントが異なる場合があると説明し、正確な残数に依存するロジックを避けるよう勧めています。Amazon API Gateway は、スロットリングとクォータを、保証された上限ではなくベストエフォートの目標値と説明しています。通知された値に基づいてリクエストのペースを調整しつつ、直前のレスポンスでクォータが残っていても、制限を示すレスポンスには引き続き対応してください。
API レート制限が重要になる場面
レート制限は、インポート、ポーリングループ、バッチジョブ、再試行ロジックなど、リクエストを大量または並列に送信するあらゆるクライアントの設計に影響します。クライアントを構築する前に、API のドキュメントで制限と制限時のレスポンスを確認してください。そのうえで、レスポンスに示された時間以上待機し、並列ワーカーが一斉に再試行しないようランダムなジッターを加え、試行回数に上限を設けてください。制限時のレスポンスに待機時間が記載されていない場合は、API のドキュメントにある代替手段を使用してください。それもなければ、試行ごとに指数関数的に増加し、上限で頭打ちになる待機時間を使用してください。即座に再試行すると負荷が増え、スロットリングが長引く可能性があります。また、GitHub を含む一部のプロバイダーは、制限中もリクエストを送り続ける連携機能は、利用を禁止される可能性があると警告しています。
Transloadit による API レート制限への対応支援
Transloadit は自社 API にレート制限を適用し、現在の制限をレート制限のページに記載しています。作成数または同時実行数の制限を超えて拒否されたリクエストには、推奨待機秒数を示す JSON エラーが返されます。Transloadit の公式 SDK は、すでにこのバックオフと再試行を実装しています。
記載された待機時間は、推奨されるバックオフです。ドキュメントでは、その時間が経過しても処理容量が利用可能になる保証はないとされています。同じページには、別個の高頻度リクエスト制限も記載されています。その制限について掲載されているレスポンスには待機時間が含まれていないため、クライアント側でバックオフの待機時間を設定する必要があります。
出典
- RFC 6585 、セクション 4:429 Too Many Requests
- RFC 9110 、セクション 10.2.3:Retry-After
- IETF Internet-Draft:HTTP の RateLimit ヘッダーフィールド(ドラフト 11 、2026 年 5月)
- GitHub Docs:REST API のレート制限
- NGINX:ngx_http_limit_req_module (リーキーバケット、バースト、拒否時のステータス)
- Amazon API Gateway:REST API リクエストのスロットリング(トークンバケット)
- Cloudflare:数百万のドメインにスケールするレート制限を構築した方法
- Amazon Builders’ Library:タイムアウト、再試行、ジッター付きバックオフ