レート制限HTTPヘッダーの理解

レート制限HTTPヘッダー

レート制限ヘッダーは、APIがレート制限の状態をクライアントに伝達する主要な方法です。これらのヘッダーを理解することは、耐障害性のあるAPIインテグレーションを構築するために不可欠です。

標準ヘッダー（IETFドラフト）

IETFにはレート制限ヘッダーの標準化を提案するドラフト（RFC 6585 + draft-ietf-httpapi-ratelimit-headers）があります：

ヘッダー	説明	例
RateLimit-Limit	ウィンドウ内の最大リクエスト数	100
RateLimit-Remaining	ウィンドウ内の残りリクエスト数	87
RateLimit-Reset	ウィンドウがリセットされるまでの秒数	30
Retry-After	待機すべき秒数（429の場合）	60

よく使われる非標準ヘッダー

多くのAPIはX-プレフィックス（標準化前）のバリアントを使用します：

HTTP/1.1 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1706140800
X-RateLimit-Used: 13
X-RateLimit-Resource: core

Reset値の解釈

ResetヘッダーはAPIによって異なる解釈がされます：

API	Reset形式	例	意味
GitHub	Unixタイムスタンプ	1706140800	このタイムスタンプでリセット
Stripe	残り秒数	1	1秒後にリセット
Twitter	Unixタイムスタンプ	1706140800	このタイムスタンプでリセット
Shopify	Unixタイムスタンプ	1706140800	このタイムスタンプでリセット

クライアント実装パターン

すべてのAPIレスポンスで：
  1. レート制限ヘッダーを解析
  2. limit、remaining、reset値を保存
  3. remaining / limit < 0.2 の場合：
     -> リクエストレートを減速
  4. remaining == 0 の場合：
     -> リセット時間までスリープ
  5. レスポンスが429の場合：
     -> Retry-Afterヘッダーを読む
     -> 指数バックオフ：wait(min(Retry-After, 2^attempt))

よくある落とし穴

1. クロックスキュー：サーバータイムスタンプとローカル時刻を比較しないこと。レスポンスのDateヘッダーとResetヘッダーの差分を使用。
2. 複数ウィンドウ：一部のAPIは複数のレート制限を同時に適用（秒あたりAND時間あたり）。すべてのリミットヘッダーを確認。
3. 共有リミット：APIキーが複数のアプリケーション間でリミットを共有する場合がある。一元的に監視。