目次
概要
Gemini APIを使った開発をしていると、様々なエラーコードに遭遇します。原因が分からないまま闇雲にリトライを繰り返すのではなく、ステータスコードごとの意味を理解しておけば、機械的に対処法を導き出すことができそうです。
ステータスコード別の意味
まず基本として押さえておきたいのが、代表的なHTTPステータスコードの意味です。
- 429：割り当て超過、いわゆるレート制限にかかっている状態
- 401：認証エラー。APIキーが無効になっている状態
- 400：リクエストの形式自体が不正な状態
- 404：エンドポイントのURLが誤っている状態
まずはどのコードが返ってきているかを確認することが、対処の第一歩になりそうです。
429エラーへの対策：指数バックオフ
レート制限による429エラーが頻発する場合、有効な対策として紹介されているのが「指数バックオフ」という実装パターンです。これは、リトライのたびに待ち時間を1秒→2秒→4秒→8秒というように倍々に増やしていく方法で、本番環境での運用を意識したエラーハンドリングとして推奨されています。固定の間隔でリトライを繰り返すと、再びレート制限に引っかかりやすくなるため、待ち時間を徐々に伸ばしていく設計が望ましいようです。
そもそも無料枠の制限値はどれくらいか
429エラーを未然に防ぐには、そもそも自分が使っているモデルの無料枠がどれくらいなのかを把握しておくことも大切です。Gemini APIの制限は、RPM(1分あたりのリクエスト数)、TPM(1分あたりのトークン数)、RPD(1日あたりのリクエスト数)という指標で管理されているようです。モデルによって数値は異なり、たとえばあるモデルでは1日あたり100リクエスト程度、より軽量なモデルでは1日250リクエスト程度、別の軽量モデルでは1分あたり5リクエスト・25万トークン程度といった制限が設定されているという報告があります。
ただし、これらの数値はモデルやリージョン、課金状況によって変動するとされており、公式ドキュメントにも固定値としては明記されていないようです。正確な最新の制限は、Google AI Studioのレート制限画面で自分のプロジェクトの状況を直接確認するのが確実とされています。開発中に429エラーが頻発するようであれば、指数バックオフで凌ぐだけでなく、そもそも無料枠から有料枠への切り替えを検討するタイミングかもしれません。
APIキー漏洩によるブロック
APIキーが漏洩していると判定された場合、そのキーはGemini APIへのアクセスがブロックされてしまいます。この場合はGoogle AI Studioにアクセスし、キーがブロックされていないかを確認した上で、新しいキーを発行する必要があります。
安全設定によるブロック
プロンプトの内容が安全設定(セーフティフィルター)によってブロックされることもあります。この場合は、API呼び出し時に設定しているsafetySettingsパラメータを見直し、必要に応じて緩和することで回避できる場合があるようです。
マルチモーダル特有の「パーツ構成の罠」
画像とテキストを組み合わせて送るようなマルチモーダルなリクエストでは、独特のエラーに遭遇することがあります。具体的には、partsの順序が想定と異なっていたり、inline_dataのMIMEタイプ指定が漏れていたりすることが原因で、400エラーが発生するケースがあるようです。開発者があまり気づきにくい落とし穴と言えそうです。
回答が途中で止まる場合
エラーコードは正常に返ってきているのに、回答が途中で止まってしまうという症状もあります。この場合、多くは生成トークン数の上限設定(max_output_tokens)が小さすぎることが原因とされています。設定値を引き上げるか、出力を分割して生成させるような指示に変えることで、解決するケースが多いようです。
まとめ：エラーコード別対応表
Gemini APIのエラーに遭遇したら、次の対応表を参考にしてみてください。
- 429(レート制限) → 指数バックオフでリトライ間隔を伸ばす
- 401(認証エラー) → AI Studioでキーの状態を確認し、必要なら再発行
- 400(リクエスト不正) → パーツの順序やMIMEタイプ指定を確認
- 404(URL誤り) → エンドポイントのURLを再確認
- 回答が途中で止まる → max_output_tokensの設定値を見直す
エラーコードという「手がかり」を正しく読み解くことが、闇雲な試行錯誤よりもずっと早い解決への近道になりそうです。
