上限に達する前にキーの使用状況を監視する
割り当てヘッダーを随時確認しておけば、リクエストが実際に拒否されるよりずっと前に、上限が近づいていることが分かります。
リクエストを失わずに429レスポンスを処理する
ステータスコード429は、400や404と同じ種類の失敗ではありません。リクエストの形式は正しく、本来なら成功していたはずですが、現在の期間の割り当てを使い切ったことを意味します。
レスポンスの内容
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}リクエストを破棄しない
最もよくある間違いは、429を400と同じように扱い、失敗として記録して次に進んでしまうことです。ユーザーやスクリプトが求めていた検索そのものは完全に有効なままで、後で実行するか、別の認証情報で実行すればよいだけです。元のリクエストの内容は破棄せず、再試行キューに入れてください。
リセット時刻を読み取る
429レスポンスのX-Quota-Resetヘッダーは、1日の割り当てがリセットされる正確な時刻を示します。バックグラウンドのジョブは、繰り返しポーリングしたり、固定の再試行間隔を当て推量で決めたりせずに、その時刻まで待機してからキューの処理を再開できます。
備えておくべき2つ目のシナリオ
429は、必ずしもその日の割り当てがすべてなくなったことを意味するわけではありません。X-Key-IPs-UsedがX-Key-IPs-Limitに達している場合、いつものアドレスからのリクエストは引き続き成功する状態でも、新しい送信元アドレスからはキーが一時的に拒否されることがあります。429の実際の原因が割り当ての枯渇なのかIPスロットの上限なのかを、どちらのヘッダーが示しているかで確認すると、解決策が変わります。前者ならリセットを待ち、後者なら同じキーを使うマシンの数を減らすことになります。
今すぐ上限を超えるための2つの方法
待つことができない場合は、すぐに使える選択肢が2つあります。1リクエストあたり€0.0001のプリペイドクレジットをチャージするか、一時的な急増ではなく繰り返し起こるパターンであれば、月額€50のUnlimitedキーに移行することです。どちらも、そもそも429の原因となった1日の上限を取り除きます。
キーの上限とネットワークの上限を区別する
無料割り当てはIPv4では/24全体、IPv6では/48全体で共有されるため、429は自分のキーの使用量だけでなく、同じネットワーク上のほかのアドレスからのトラフィックが原因で起こることもあります。キーのアップグレードで本当に解決するかどうかを判断する前に、X-Quota-UsedとあわせてX-Quota-Network-Usedを確認し、2つの状況を見分けてください。
避けるべき間違い
429が返ってきた瞬間に、失敗したリクエストを間隔を空けないループですぐに再試行しても、すでに使い切った割り当ての上に失敗した呼び出しを積み重ねるだけで、成功するリクエストには少しも近づきません。すぐにエンドポイントを再び叩き続けるのではなく、ヘッダーのリセット時刻まで、あるいはそのコードでヘッダーを読まない場合は妥当な固定の遅延時間だけ待ってください。
429を「失敗した」ではなく「少し待ってからもう一度試す」と扱えば、作業を失うことなく、割り当てのリセットをまたいでキューをスムーズに進められます。API全体のエラー形式の詳細はエラーのページに、現在の割り当てのオプションは料金ページに記載されています。