Telm は API を 2 通りで計測します。分あたりのレート制限(バースト上限)と、日次枠(UTC の 1 日のための総予算)です。どちらもプランに応じてスケールします。計測対象のレスポンスはすべて X-Quota-Limit、X-Quota-Used、X-Quota-Reset を返すので、残りの予算が常に分かり、超過するとどちらの制限も Retry-After ヘッダーとともに 429 を返します。
12 つの制限:分あたりのレートと日次枠
別々の上限が 2 つあります。分あたりのレート制限 は、任意の 1 分内にできるリクエスト数を上限とし、バーストを平滑化します。日次枠 は全体の予算で、UTC の 1 日を通じてできる計測対象の呼び出し数を上限とします。
これらは独立しています。日次枠が十分残っていても分あたりの制限に達すること(単に送るのが速すぎる)も、分あたりの制限に十分収まりつつ日次枠を使い切ること(その日を使い切った)もありえます。どちらも 429 ステータスを返しますが、理由は異なります。区別するには本文のエラー コードを確認してください。
- 分あたりのレート制限 — バースト上限で、毎分リセットされます。
- 日次枠 — その日の計測対象の総呼び出し数で、UTC 深夜にリセットされます。
- 枠はアカウントごとに一度数えられ、あなたのすべてのキーで共有されます。
2プラン別の日次枠
日次枠は、UTC の 1 日あたりにできる計測対象の API 呼び出し数で、プランに依存します。カウンターはあなたのすべてのキーで共有され、あなたが管理するグループの中で最良のプランに従います。有料サブスクリプションがなければ Free ティアです。
ウィンドウは UTC のカレンダー日なので、使用カウンターは UTC 深夜にゼロへリセットされます。バッチ スパム判定は、リクエスト全体で 1 呼び出しではなく、バッチ内の項目ごとに 1 呼び出しかかります。
- Free — 1 日 100 呼び出し。
- Basic — 1 日 1,000 呼び出し。
- Pro — 1 日 10,000 呼び出し。
- Business — 1 日 50,000 呼び出し。
3プラン別の分あたりレート制限
日次枠に加えて、各 API キーは、そのプラン ティアに応じて分あたりのリクエスト数に制限されます。これは平滑化の制限で、日次予算がまったく使い切られていなくても、単一のクライアントが 1 秒で巨大なスパイクを送るのを止めます。
別途、プラットフォームを安定に保つため、API 全体にわたって広い IP ごと・アカウントごとの上限が適用されます。通常の使い方、つまり一定でペースの取れたリクエストでは、これらに触れることは決してありません。悪用的なバーストにのみ発動します。
- Free と Basic — 分 60 リクエスト。
- Pro — 分 600 リクエスト。
- Business — 分 1,800 リクエスト。
- リクエストは一度にまとめて撃つのではなく、分散させてください。
4残りの予算を読む
残りの枠がどれだけあるか推測する必要は決してありません。計測対象のレスポンスは、成功でも失敗でも、3 つのヘッダーを含みます。X-Quota-Limit(日次の上限)、X-Quota-Used(今日使った呼び出し数)、X-Quota-Reset(カウンターがリセットされる UTC での瞬間)です。
スパム判定エンドポイントは、同じ数値をレスポンス本文の quota オブジェクト内にも反映するので、ヘッダーを解析せずに残りの予算を読めます。これらを使って、自分のリクエストのペースを取り、使い切る前に自らへ警告してください。
- X-Quota-Limit — 日次の呼び出し上限。
- X-Quota-Used — 今日これまでに使った呼び出し数。
- X-Quota-Reset — UTC でのリセット時刻(RFC 3339)。
- スパム判定のレスポンスは、同じフィールドを持つ quota オブジェクトも含みます。
5429 で何が起きるか
どちらかの制限を越えると、API は何秒待つべきかを伝える Retry-After ヘッダーとともに HTTP 429 を返します。分あたりのレート制限では、Retry-After は約 1 分です。日次枠では、本文が daily_quota_exceeded コードに加えてあなたのプラン・上限・使用数・リセット時刻・アップグレードのヒントを持ち、Retry-After は UTC 深夜までカウントダウンします。
429 を扱う正しい方法は、エンドポイントを叩き続けるのではなく、Retry-After の遅延の後にバックオフして再試行することです。行儀の良いクライアントはヘッダーを読んで一時停止します。すぐに再試行し続けるクライアントは、ただブロックされたままです。
- 429 rate_limit_exceeded — 送るのが速すぎました。約 1 分待ちます。
- 429 daily_quota_exceeded — その日を使い切りました。UTC のリセットまで待つか、アップグレードします。
- 再試行の前に、必ず Retry-After ヘッダーを尊重してください。