レート制限エラーとは？ - 解説

レート制限エラーとは、ある期間内に許可された回数を超えたために、サービスが意図的にリクエストを拒否している状態で、一般的には HTTP 429 として返されます。

サービスは自身を保護するために、クライアントが単位時間あたりに送信できるリクエスト数に上限を設けています。CI がその上限を超えると、多くの場合はパッケージインストールやイメージのプルが集中したタイミングで、サービスはリクエストを処理する代わりにレート制限エラーを返します。これはウィンドウがリセットされれば解消される一時的な状態です。

レート制限とは何か

レート制限とは、特定のクライアントや IP から一定期間（毎分、毎時）に一定数のリクエストしか許可しないというポリシーです。しきい値を超えると、サービスはウィンドウがリセットされるまで以降のリクエストを拒否し、通常はステータス 429 Too Many Requests、時には 403 を返します。

CI がレート制限を引き起こす理由

多数の並列 job が、共有された 1 つの IP から同じイメージやパッケージをプルする。
レジストリへの未認証リクエストは、通常より厳しい制限が課される。
タイトなループでの API 呼び出し（ステータス更新、コメント）のバースト。
バックオフなしのリトライが、制限されたウィンドウ中にさらにリクエストを積み上げる。

レスポンスの読み方

レート制限のレスポンスには、いつ再試行してよいかを示す Retry-After ヘッダーや残りクォータのヘッダーが含まれることが多くあります。それらを尊重するのが正しい振る舞いです。すぐにリトライして問題を深刻化させるのではなく、指示された時間だけ待ちましょう。

一時的、ただし注意点あり

レート制限エラーはウィンドウがリセットされるため一時的で、待機後のリトライは通常成功します。ただし正しいリトライはバックオフを伴い Retry-After を考慮したものです。即座にリトライすると次のウィンドウを消費するだけです。認証とキャッシュにより、そもそも制限に達する頻度を減らせます。

Latchkey の視点

Latchkey の自己修復マネージド runner は、レジストリの 429 のようなレート制限エラーを一時的なものとして扱い、適切なバックオフを伴ってリトライします。そのため、忙しい build 中の一度きりのレート制限で build が失敗することはなく、制限のかかったサービスに過度な負荷をかけることもありません。

重要なポイント

レート制限エラーは、許可されたレート（多くの場合 429）を超えたリクエストを拒否する。
CI は並列プル、未認証リクエスト、バーストによって制限に達する。
Retry-After を尊重し、すぐにリトライせず待機する。
一時的でリトライ可能だが、バックオフを伴う場合に限る。