
gemini-throttle: Gemini APIの429を「待って解決する」プロキシ
AIエージェントがGemini APIを呼び出すとき、1分間に10〜20リクエストという厳しい制限にすぐ引っかかる。429エラーが返り、エージェントの処理が止まる。この問題を「待機して再試行」で解決するプロキシを開発した。
問題: AIエージェントと429
Gemini APIの無料枠は、1分間に10〜20リクエストという短時間レートリミット(RPM/TPM)が厳しい。人間が手動でAPIを叩く分には問題ないが、AIエージェントがツール呼び出しを連続実行する場面では、数秒で上限に達する。
429(Too Many Requests)が返ると、Hermesなどのエージェントフレームワークは3回リトライし、失敗するとターンを中断してユーザーに返す。cronジョブやバッチ処理が遮られる。
429は時間経過で解除される。リミットは固定ではなく時間窓だ。待てば解決する。問題は「待つ仕組み」がないことだった。
既存の対策とその限界
コミュニティではいくつかの対策が試みられている。
APIキー・ローテーション: 複数のAPIキーを用意し、429を受けたキーをスキップして次に切り替える。しかしGoogleは同一IPからの複数キー使用を検出する可能性があり、規約違反のリスクがある。
スライディングウィンドウ・プロキシ: 上限に達する前にリクエストをブロックする。しかし「待たない」ため、エージェントがリトライを繰り返し、処理が進まない。
フォールバックチェーン: 429を受けたら別プロバイダ(DeepInfra, OpenRouter等)に逃げる。Gemini以外の429には有効だが、Geminiの短時間429(1分窓)は待てば解除されるため、逃げる必要がない。逃げるとGeminiの枠が無駄になる。
解決: gemini-throttle
`gemini-throttle`は、HermesとGoogle AI Studioの間に立つリバースプロキシだ。ポート8899でローカルバインドし、Gemini APIへのリクエストを中継する。
429を受けたときの動作:
レスポンスから待機秒数を抽出する(Retry-Afterヘッダ → RetryInfo JSON → 本文文言 → デフォルト10秒の3段フォールバック)2. その秒数だけ実際に待機する(最大65秒)3. リクエストを再試行する(最大3回)
さらに、429が発生する前にリクエストを平滑化するTokenBucket(10 req/min)を事前スロットリングとして実装した。
設計の核心: Park(待機)
429の本質は「時間窓の枯渇」だ。固定の制限ではなく、時間経過で回復する。だから待てば解決する。
フォールバック(別プロバイダへの逃げ)は、Gemini以外の429に対して有効だ。しかしGeminiの短時間429に対してフォールバックすると、Geminiの枠が無駄になる。Geminiの短時間429はPark(待機)で解決するのが正しい。
この「Park」と「Fallback」の分離が、gemini-throttleの設計原則だ。
アーキテクチャ
Application (Hermes, etc.)
↓
127.0.0.1:8899 (gemini-throttle)
↓ (429 → park → retry)
generativelanguage.googleapis.com/v1beta/openai統合方法
Hermesの`config.yaml`に`custom_providers`として追加する:
custom_providers:
- name: gemini-throttled
base_url: http://127.0.0.1:8899/v1
api_key: ${GOOGLE_API_KEY}
model: gemini-3.5-flash-lite既存の`gemini`プロバイダは変更しない。`gemini-throttled`を明示的に選択する時だけ使う。
注意: GEMINI_BASE_URL は使用禁止
`.env`に`GEMINI_BASE_URL`を設定すると、Hermesのconfig読み込み機構が全プロバイダのbase_urlをGoogleエンドポイントに上書きする。DeepInfra等の他のプロバイダがGoogleに流され、404が発生する。過去に8つのcronジョブが全滅した事故の原因だった。
gemini-throttleは`custom_providers`の個別エントリとして統合し、既存プロバイダに影響を与えない。
仕様
対象: `generativelanguage.googleapis.com` へのリクエスト
対象外: 他の全プロバイダ(DeepInfra, OpenRouter, fable-distill等)
対象外: 日次リミット(RPD)、認証失敗(401)、モデル不在(404)
最大待機: 65秒
最大リトライ: 3回
バインド: 127.0.0.1(外部露出禁止)
APIキーはプロキシに保存しない(クライアントのAuthorizationヘッダを中継)
ライセンス
MIT License. Copyright (c) 2026 Panda Captain & Reika AI.
GitHub: https://github.com/Captain-Panda2024/gemini-throttle
