バケツと水で理解するMessaging APIのレート制限とトークンバケット方式
こんにちは！テクニカルライターの古木です。
Messaging APIの各エンドポイントには、リクエストを送信する頻度の上限である「レート制限」があります。レート制限を超えたリクエストには、429 Too Many RequestsのステータスコードとThe API rate limit has been exceeded. Try again later.のエラーメッセージが返されます。
レート制限が「60リクエスト/時」であると聞くと、毎時0分にリクエスト数がリセットされるような仕組みを想像するかもしれませんが、Messaging APIのレート制限は、そのような仕組みではありません。
今回の記事では、Messaging APIのレート制限の仕組みについて掘り下げ、Messaging APIで採用しているトークンバケット方式について説明します。
トークンバケット方式の概念説明
トークンバケット方式では、リクエストの送信に使えるトークンが、上限のあるバケットに蓄えられます。リクエストを送信するとトークンが消費され、消費された分のトークンは時間の経過に応じて徐々にバケットに補充されます。
トークンを水に置き換えると、次のように考えることができます。
- バケツには、水（利用可能なトークン）が貯まっています。
- コップ1杯分の水（1リクエスト分のトークン）をすくうと、バケツの水が減ります。
- 蛇口からは、水が一定のペースで補充されます（時間の経過に応じたトークンの補充）。
- バケツの容量を超えて水を蓄えることはできません。
コップで水をすくうペースが、水を補充するペースよりも遅い間は、蛇口からの補充によってバケツ内の水が保たれます。一方、コップで水をすくうペースが、蛇口から水を補充するペースを上回る状態が続くと、やがてバケツの中の水が足りなくなります。水が足りない状態では、コップで水をすくうことはできません。
この水が足りない状態は、リクエストに必要なトークンが不足している状態を表します。この状態でリクエストを送信すると、429 Too Many Requestsが返されます。
なお、これらの図はトークンバケット方式の考え方を示す模式図です。実際のトークン数や補充間隔を示すものではありません。
トークンは時間の経過とともに徐々に補充される
バケツと水の例えで示したとおり、トークンバケット方式では、消費された分のトークンが時間の経過に応じて徐々にバケットに補充されます。レート制限が「60リクエスト/時」のエンドポイントであれば、1リクエスト分のトークンが補充されるまでに1分かかる計算です。
また、バケットに必要なトークンが残っていれば、補充ペースを一時的に上回るペースでリクエストを送信できます。たとえば、レート制限が「60リクエスト/時」で、バケットに60リクエスト分のトークンが蓄えられている場合、次のようになります。
- 1秒間に60リクエストを送信する。
- すべてのトークンが消費され、一時的にバケットが空になる。
- 1分が経過すると1リクエスト分のトークンが補充され、1リクエストを送信できるようになる。
- トークンが補充される前にリクエストを送信すると、
429 Too Many Requestsが返される。
- トークンが補充される前にリクエストを送信すると、
つまり、レート制限が原因の429 Too Many Requestsを受け取った直後は、バケットに蓄えられているトークンが不足している状態です。そのため、リクエスト頻度を下げ、トークンが補充されるまで時間を置いてから、再度リクエストを送信してください。
大量のリクエストを送信する必要がある場合は、短時間に集中させず、キューなどを使って送信のペースを調整すると、トークンを使い切りにくくなります。
Messaging APIのレート制限は、チャネル単位かつAPI機能（エンドポイント）ごとに適用されます。たとえば、複数のサーバーやツールから同じチャネルの同じエンドポイントを呼び出す場合、それぞれのリクエストは同じレート制限の対象となるため、注意してください。
おわりに
今回は、Messaging APIのレート制限の仕組みであるトークンバケット方式について説明しました。
トークンバケット方式では、バケットに必要なトークンが残っていれば、一時的にリクエストの送信ペースがトークンの補充ペースを上回っても、リクエストを送信できます。ただし、リクエストを短時間に集中させないことと、レート制限超過を示すエラーメッセージが返されたら次のリクエストまで時間を置くことを意識してください。
レート制限の値や適用範囲について詳しくは、『Messaging APIリファレンス』の「レート制限」を参照してください。
この記事の著者
ふるき（テクニカルライター）：LINE Developersサイトのドキュメントを担当。テクニカルライティングに関するコミュニティ「Technical Writing Meetup」を主催。