Nano Banana API が失敗したら、最初にやることは再試行でも API key の交換でもありません。まず失敗の分岐を決めます。429 RESOURCE_EXHAUSTED はクォータまたは rate limit、503 UNAVAILABLE は容量、504 DEADLINE_EXCEEDED は timeout、HTTP 成功なのに画像がない場合は response parts と inlineData、拒否メッセージは permission、safety、file resource、gateway を分けて見ます。
| 表示される現象 | 最初の安全な確認 | 次の動き |
|---|---|---|
429 RESOURCE_EXHAUSTED | 同じ project / model の実際の制限を確認する。 | jitter 付き backoff、queue、または 429 専用手順へ進む。 |
503 UNAVAILABLE / 504 DEADLINE_EXCEEDED | 同じ model、endpoint、project、key、payload、input で再検証する。 | 503 は容量、504 は timeout と負荷を直す。 |
| 画像なし、text only | response parts を走査し image part を確認する。 | parser、modality、safety、file reference を修正する。 |
| 拒否メッセージ | 403、safety finish、file access、gateway denial を分ける。 | 拒否した owner だけを直す。 |
事実の境界：Google Gemini API の troubleshooting、image generation、rate limits、Batch API、Files API は 2026 年 4 月 19 日に確認済みです。古い quota 表、固定の低負荷時間、障害率の数字、必ず直る表現は採用しません。
429 RESOURCE_EXHAUSTED はまずクォータを見る
429 RESOURCE_EXHAUSTED は、まず project または model の quota pressure として扱います。key を交換しても、同じ project に属していれば同じ制限に当たることがあります。先に Google 側で現在の project limit と model limit を見てください。
次に必要なのは、回数に上限を持つ backoff です。全 worker が同時に戻らないよう jitter を入れます。リアルタイムでない画像生成は queue や Batch API に逃がし、ユーザーの同期リクエストと同じ quota を奪い合わないようにします。
通常の負荷で毎回 429 が出るなら、retry の問題ではなく容量設計の問題です。詳しい分岐は Gemini Image 429 rate limit、広い quota 設計は Gemini API rate limits が適しています。
503 と 504 は同じ修正にしない
503 UNAVAILABLE は一時的な availability または capacity の分岐です。prompt が悪い、billing が悪い、key が悪いとはまだ言えません。同じ経路で一度だけ再検証します。結果が 503 のままなら capacity、429 に変われば quota、400/403 に変われば client branch へ移ります。
504 DEADLINE_EXCEEDED は timeout です。重い input、長い生成、短すぎる client timeout、または backend の遅延が原因になります。504 では、単純な連続 retry よりも timeout を上げる、payload を軽くする、入力ファイルを減らすほうが効きます。
503/504 が安定して続く場合は Gemini 3 Pro Image 503 overloaded の手順に移すと、容量と timeout の証拠を分けて扱えます。
画像なしは response parts から見る
HTTP success でも画像 part がないことがあります。Gemini の画像出力は response の parts に入るため、最初の text part だけを読む実装では画像を見落とします。すべての candidate と part を走査し、inlineData と image MIME type を探してください。
image part がなければ、次に output modality、finish reason、file reference を確認します。画像出力を要求していない、safety finish で止まった、local path を API resource と誤解している、古い file URI を使っている、というケースがよくあります。
修正は parser を直すだけで終わることもあります。image part だけ保存し、text part と safety reason はログに残し、file は API が読める形で渡します。
拒否メッセージは権限だけとは限らない
拒否は一つの原因名ではありません。403 PERMISSION_DENIED なら key、project、API enablement、permission を確認します。HTTP success で finishReason: SAFETY なら safety branch です。file resource が見つからない場合は Files API の name、URI、MIME type、state、project ownership を確認します。gateway を使っている場合は、Google の upstream status と gateway status を別に記録します。
一度に key、model、endpoint、prompt、provider を変えると、何が拒否を直したのか分からなくなります。拒否した owner を先に決め、その owner だけを直してください。
同じ経路の再検証で原因を残す
同じ経路の再検証では、model、endpoint、project、key、payload、input asset、request format を固定します。その状態で分岐が安定するか、別の分岐に変わるかを見ます。
| 再検証結果 | 意味 | 次の動き |
|---|---|---|
| まだ 429 | quota branch が安定 | backoff、queue、Batch API、429 route |
| まだ 503 | capacity branch が安定 | bounded retry、queue、503 route |
| 504 に変化 | timeout が見えた | timeout を上げる、負荷を下げる |
| 成功だが画像なし | response shape が見えた | parts、inlineData、modality、safety、file を確認 |
| 403 または拒否 | permission / safety / file が見えた | owner を直す |
分岐が証明された後にだけ、変数を一つずつ変えます。持続的な 429 では Nano Banana 2 alternative 429 を検討できます。
よくある質問
503 は Nano Banana API 全体の停止ですか？
必ずしもそうではありません。現在の request path が availability または capacity branch に入ったという意味です。同じ経路で再検証してから判断します。
課金を有効にすれば 503 は消えますか？
課金は quota と tier に影響しますが、証明済みの 503 capacity branch を自動で直すものではありません。429 と 503 は分けてください。
テキストだけ返って画像がないのはなぜですか？
parser が image part を見ていない、画像出力を要求していない、safety finish になった、または input file が API から読めない可能性があります。
Request Denied はどこから見るべきですか？
HTTP status から見ます。403 なら permission、HTTP success で safety finish なら safety、file を使う request なら resource URI と project ownership を確認します。
いつ model や provider を切り替えるべきですか？
分岐を証明してからです。継続する 429、継続する 503、明確な safety limit、file/gateway policy がある場合だけ、次の route を評価します。