What — 回数の上限を超えると 429 が返る

レートリミットは、一定時間に受け付けるリクエスト数の上限。 超えた分は処理されず、ステータスコード 429（Too Many Requests） が返る。 1利用者の連打からサーバーを守る仕組みで、公開APIにはほぼ必ずある。

いま何回残っているかは、レスポンスヘッダに書いてある。

ヘッダ名はAPIごとに少し違うので、ドキュメントの「Rate limit」の節で確認する。

How — 429 は「待って再送」が正解

429 は失敗ではなく「待てばまた通る」の合図。対応は2段構え。

• Retry-After があれば、その秒数だけ待って同じリクエストを再送する
• 無ければ、待ち時間を倍々に伸ばしながら再試行する（指数バックオフ：1秒→2秒→4秒…）

残量の確認は curl -i でヘッダごと表示すればいい。

curl -i https://api.github.com/users/octocat

落とし穴

• 429 をエラーとして処理を止めてしまう。4xx の中で 429 だけは「リクエストを直す」のではなく「待つ」が正解。リトライ対象として特別扱いする
• ページネーション の全件ループが無自覚に上限を食い尽くす。ループを書くときは Remaining を見ながら叩く

関連

• API — API まわりの地図
• HTTPレスポンスの構造 — ヘッダがどこに入っているかはこちら
• エラーレスポンス — 429 以外のエラーの読み方