429 Too Many Requests

使い方

429 Too Many Requests ステータスコードは、HTTP リクエストの数が許容されたしきい値を超えたことを示します。これはたとえば、サーバーが1時間あたりの API 呼び出し数を制限したい場合に発生します。

仕様は、サーバーが HTTP リクエストをどう数えるか、ユーザーをどう識別するかを定義していません。レート制限はリソース単位、ユーザー単位、サーバー全体、あるいは複数のサーバーにまたがって行われます。ユーザーの識別は資格情報を使って行われるか、あるいはクッキーを使って行われます。

サーバーは任意で、いつリクエストが再び受け付けられるかをクライアントに伝えるため Retry-After の HTTP ヘッダーを含めます。

注意

レート制限は一定の時間枠におけるリクエストの総数に上限を設ける（ハードな打ち切り）のに対し、スロットリングはレスポンスをキューに入れたり遅延させたりしてリクエストの処理を遅くします。待機時間は Retry-After ヘッダーに依存します。Retry-After がない場合、一般的な時間枠は API によって 60 秒から 24 時間の範囲です。VPN の利用者は他の多くの利用者と IP アドレスを共有するため、IP 単位のレート制限は同じサーバー上のすべての VPN 利用者に影響します。

SEO への影響

Googlebot は 429 をサーバーエラーのシグナルとして扱います。サイトが 429 レスポンスを返すと、Google はサイト全体のクロール頻度を一時的に低下させます。通常のレスポンスが再開されると、クロール頻度は徐々に回復します。他の 4xx コードとは異なり、429 レスポンスはクロールバジェットに影響します。インデックスされた URL で 429 レスポンスが継続すると、検索結果からの削除につながります。Googlebot の速度を落とすには、429 が正しいステータスコードです。401 と 403 はクロール頻度を低下させません。Bingbot も 429 レスポンスを受けるとクロール頻度を低下させます。Bing はさらに、ステータスコードに基づくスロットリングの代替として robots.txt の crawl-delay をサポートしています。

例

クライアントがリソースを要求し、サーバーは 429 Too Many Requests で応答します。

リクエスト

GET /current-news HTTP/1.1
Host: example.com

レスポンス

HTTP/1.1 429 Too Many Requests
Retry-After: 1800
Content-Type: text/html
Content-Length: 173

<html>
  <head>
    <title>Request Limit Exceeded</title>
  </head>
  <body>
   <p>The request limit has been reached.
   Try again in 30 minutes.</p>
  </body>
</html>

対処方法

レスポンスの Retry-After ヘッダーを確認します。その値は、サーバーが再びリクエストを受け付ける時点を示す秒数または HTTP 日付のいずれかを指定します。示された時刻まですべてのリクエストを停止します。

再試行のあいだにジッターを伴う指数バックオフを実装します。失敗のたびに待機時間を倍にし（1秒、2秒、4秒、8秒）、複数のクライアントが同じ瞬間に再試行して新たなトラフィックの急増を生まないようランダムなオフセットを加えます。

上限に達する前にレート制限のヘッダーを監視します。多くの API は X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset の各ヘッダーを含めます。残り回数を追跡し、先回りしてリクエストのペースを落とします。

標準化されたレート制限のフィールド

事実上の標準である X-RateLimit-* ヘッダーに加え、IETF はクォータとリセットを伝えるための RateLimit および RateLimit-Policy のレスポンスフィールドを標準化しつつあります。

クライアント側で送信リクエストをキューに入れます。送出レートを制御したリクエストキューは、バーストが制限を超えるのを防ぎます。エンドポイントが一括操作をサポートしている場合は、複数の操作を1回の API 呼び出しにまとめます。

リクエスト間で変化が見込まれないデータについてはレスポンスをキャッシュします。同一内容の冗長な呼び出しは、不要なレート制限の消費の最も一般的な原因です。

nginx のサーバー側では、limit_req_zone と limit_req のディレクティブが IP 単位またはエンドポイント単位のレート制限を制御します。limit_req_status 429; を設定して、レート制限されたリクエストがデフォルトの 503 ではなく正しいステータスコードを返すようにします。短いトラフィックの急増でクライアントを即座に拒否しないよう、burst と nodelay のパラメーターを使います。

AWS API Gateway では、ステージまたはメソッドのレベルでスロットリングの設定を行います。デフォルトのしきい値が厳しすぎる場合は、想定されるトラフィックのパターンに合わせてレートとバーストの容量を増やします。

コードリファレンス

.NET

HttpStatusCode.TooManyRequests

Rust

http::StatusCode::TOO_MANY_REQUESTS

Rails

:too_many_requests

http.StatusTooManyRequests

Symfony

Response::HTTP_TOO_MANY_REQUESTS

Python3.5+

http.HTTPStatus.TOO_MANY_REQUESTS

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_TOO_MANY_REQUESTS

Angular

@angular/common/http/HttpStatusCode.TooManyRequests