上限に達する前にキーの使用状況を監視する
割り当てヘッダーを随時確認しておけば、リクエストが実際に拒否されるよりずっと前に、上限が近づいていることが分かります。
X-Quota-Used と X-Quota-Limit ヘッダーを正しく読む
APIからのすべてのレスポンスには、成功したかどうかにかかわらず、割り当てに対する現在の状況を正確に示すヘッダー一式が付いています。それらを正しく読み取るには、それぞれが何をカウントしているかを理解する必要があります。
基本となる2つ
X-Quota-Limitは、現在の割り当ての大きさで、1日あたりの無料割り当て、またはUnlimitedパッケージにおける実質的な上限のいずれかです。X-Quota-Usedは、現在の期間中にその割り当てに対してこれまでにカウントされたリクエスト数です。X-Quota-Free-Remainingがすでに計算してくれるため、一方から他方を手作業で引き算する必要はありません。
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00Zキーの使用量とネットワークの使用量
X-Quota-Usedはキーに紐づく使用量を、X-Quota-Network-Usedは周囲のネットワークからの使用量を反映します。無料割り当ては、キーの有無にかかわらず、同じ/24内のすべてのIPv4アドレスと同じ/48内のすべてのIPv6アドレスで共有されるからです。同じアドレスブロックの背後にある複数のサーバーからキーを呼び出す場合、ネットワークの数値は、個々のサーバーが自分のトラフィックから想定するよりも速く増えていきます。
IPスロットの2つ
X-Key-IPs-UsedとX-Key-IPs-Limitは、まったく別のことを表します。キーごとに許可される2つまたは3つのアドレスというローリング上限に対して、最近この特定のキーを使った異なる送信元アドレスの数です。1台のサーバーから呼び出されるキーでは、ここに常に1が表示されます。無関係な複数のサーバーで共有されているキーや、スクリプトにコピーされて多数のマシンで実行されることになったキーでは、上限に向かって増えていきます。これはリクエストの割り当てとは別に注視する価値があります。無料リクエストが十分に残っていても、キーがブロックされることがあるからです。
クレジットとリセット時刻
X-Credits-Remainingは、無料割り当てを超えて1リクエストあたり€0.0001でクレジットを消費している場合の、プリペイド残高を示します。X-Quota-Resetは、現在の1日あたりの割り当てがリセットされる正確な時刻を示し、自分の時計をもとに決まった時刻を想定するよりも信頼できます。
これらのヘッダーをもとに構築すべきもの
毎回の呼び出しの後にこれらのヘッダーを読み取るダッシュボード、アラート、あるいは1行のログがあれば、別のレポート用の呼び出しなしに、使用量をリアルタイムで把握できます。数値は、すでに行ったリクエストのレスポンスに含まれて届くからです。読み取りに追加のコストはかかりません。リクエストが成功した場合もエラーで返ってきた場合も、もともと送信していたすべてのリクエストに付いてくるからです。
避けるべき間違い
何か問題が起きたときにだけこれらのヘッダーを読むと、割り当ての問題に気づくのはユーザーと同じタイミングになります。少なくともX-Quota-Free-RemainingとX-Credits-Remainingを定期的に、またはトラフィックの少ない連携では毎回の呼び出しの後に記録してください。そうすれば、上限に向かってゆっくり近づいていることが、突然の大量の429レスポンスではなく、ダッシュボード上の傾向として見えるようになります。
問題に気づくのを429まで待つのではなく、すべてのレスポンスで割り当てヘッダーを読み取ることが、落ち着いてペースを落とせるか、不意を突かれるかの違いになります。ヘッダーの完全な一覧はレート制限のページに記載されています。