APIの429エラーとは？連携を急がせすぎないためのレート制限

レート制限は、一定の時間に受け付ける量を調整する

APIは、ソフトウェア同士がデータや操作をやり取りする窓口です。一つの利用者が短時間に大量のリクエストを送ると、受け取る側が処理しきれなくなる場合があります。その量を制御する仕組みがレート制限です。

MDNの429 Too Many Requestsの説明では、一定時間にリクエストが多すぎることを示す応答として紹介されています。応答にRetry-Afterが含まれ、再試行まで待つ時間の目安を伝える場合もあります。

ただし、制限を利用者単位、IPアドレス単位、操作単位などのどこに設けるかはサービスによります。429という数字だけで、どの上限に触れたかまでは判断できません。

送信の速さと、同時に動く数は別に見る

毎秒の送信件数が少なくても、一件の処理が長くかかれば、実行中の処理が積み上がることがあります。そこで同時実行数にも制限を設けるサービスがあります。

Stripeのレート制限の公式資料は、リクエストの頻度と同時実行数の制限を区別し、応答ヘッダーで理由を示す仕組みを説明しています。これはStripeの仕様であり、ほかのAPIが同じヘッダーや上限を使うという意味ではありません。

たとえば、架空の在庫連携で大量の商品を同時に更新する場面なら、「一秒に何件送るか」と「何件を並行して処理するか」を別々に見ると、原因を追いやすくなります。

すぐに全件を送り直すと、混雑が続く

失敗した処理を一斉に送り直すと、再び同じ制限へ達する可能性があります。元のリクエストに再試行分が加わり、負荷を増やすことにもなります。

Stripeは、再試行の間隔を段階的に延ばし、待ち時間にばらつきを加える方法を案内しています。間隔を延ばす方法は指数バックオフ、ばらつきを加える方法はジッターと呼ばれます。複数の処理が同じ瞬間に再開することを避けるための考え方です。

実装では、そのAPIの待ち時間の指示やSDKの動作を先に確認します。SDKがすでに再試行する場合、アプリ側でも重ねて再試行し、想定以上の回数になることがあるためです。

待ち続ければ必ず成功するわけではありません。回数や時間の上限、キャンセル、最終的な失敗表示を決めることは、利用者が次の行動を選ぶためにも役立ちます。

更新処理は、送り直してよいかも確かめる

読み取りと違い、注文作成などの更新は、再送によって二重に実行されると困ります。待ち時間の調整だけでなく、同じ依頼を識別する仕組みが必要な場合があります。

また、Stripeでは429のすべてがレート制限によるものではなく、ロック待ちのタイムアウトもあり得ると説明されています。エラー本文やヘッダーを見ずに、数字だけで同じ対処へ進まないことが大切です。

まとめ

429が返ったら、制限の対象、送信の速さ、同時実行数を分けて調べます。公式の再試行条件に従い、待つ上限と失敗後の扱いまで決めることが、落ち着いて連携を回復する助けになります。

更新の重複を防ぐ考え方は、APIの再試行と冪等性で説明しています。