Когда Nano Banana API перестает возвращать нормальный результат, не начинайте с замены ключа, модели или провайдера. Сначала определите ветку сбоя. 429 RESOURCE_EXHAUSTED указывает на квоты или rate limit проекта. 503 UNAVAILABLE начинается как ветка емкости. 504 DEADLINE_EXCEEDED относится к таймауту. Успешный HTTP-ответ без изображения требует проверки parts, inlineData, output modality, safety finish и file resource. Формулировка request denied делится на permission, safety, key/project, file access или gateway policy.
| Симптом | Первая безопасная проверка | Следующее действие |
|---|---|---|
429 RESOURCE_EXHAUSTED | Проверьте живые лимиты проекта и модели. | Backoff с jitter, очередь или отдельный маршрут 429. |
503 UNAVAILABLE / 504 DEADLINE_EXCEEDED | Повторите тот же путь: модель, endpoint, проект, key, payload и input. | Для 503 используйте bounded retry; для 504 правьте timeout или нагрузку. |
| Нет изображения или только текст | Обойдите все response parts и найдите image data. | Исправьте parser, modality, safety или file reference. |
| Request denied | Разделите 403, blocked key, safety finish, file resource и gateway denial. | Исправляйте владельца отказа, а не все переменные сразу. |
Граница фактов: официальные документы Google Gemini API по troubleshooting, image generation, rate limits, Batch API и Files API проверены 19 апреля 2026 года. Старые таблицы лимитов, проценты инцидентов, обещания непиковых окон и гарантированные исправления здесь не используются.
429 RESOURCE_EXHAUSTED сначала означает давление на квоту
429 RESOURCE_EXHAUSTED не доказывает поломку модели. Это прежде всего сигнал, что текущий проект или модель достигли квотного давления. В Gemini API лимиты обычно связаны с проектом, поэтому второй ключ в том же проекте не обязан дать новый запас.
Порядок действий простой: откройте фактические лимиты проекта, проверьте модель и tier, затем запускайте retry только с верхней границей попыток. Jitter нужен, чтобы параллельные воркеры не вернулись в API одной волной. Если задача не пользовательская и не срочная, лучше отправить ее в очередь или Batch API, чем держать синхронный цикл.
Если 429 повторяется при обычной нагрузке, это уже не локальный всплеск, а вопрос capacity planning. Для точного разбора используйте ветку Gemini Image 429; для общей архитектуры лимитов смотрите Gemini API rate limits.
503 и 504 требуют разных действий
503 UNAVAILABLE говорит о временной недоступности или перегрузке. Он не означает, что billing, key или prompt обязательно неверны. Сначала повторите тот же запрос без изменений. Если ответ снова 503, ветка емкости сохраняется. Если стал 429, переходите в квоты. Если появился 400 или 403, прекращайте лечить это как перегрузку.
504 DEADLINE_EXCEEDED имеет другой смысл: запрос не уложился в бюджет времени. Это может быть слишком тяжелый input, сложная генерация, короткий client timeout или перегруженный backend. Для 504 полезнее поднять timeout или снизить нагрузку, чем просто быстро повторять тот же запрос.
Точная ветка для устойчивых 503/504 находится здесь: исправление Gemini 3 Pro Image 503 overloaded.
Отсутствие изображения начинается с проверки response parts
HTTP success может вернуть текст и не вернуть image part. Код приложения часто ошибается, когда ожидает изображение в одном фиксированном поле или сохраняет только первый part. Для Gemini image generation нужно пройти по candidates, content parts и проверить inlineData с image MIME type.
Если image data нет, проверьте четыре вещи. Запрос действительно просит image output. Response не завершился safety finish. Входной файл был загружен как API resource, а не передан локальным путем. Gateway не преобразовал ответ и не потерял image part.
После этого исправление обычно маленькое: явно запросить изображение, сохранить только настоящий image part, логировать finish reason и file URI отдельно. Без этой проверки no-image нельзя считать outage.
Request denied нужно разбирать по владельцу отказа
Request denied может прийти из разных слоев. 403 PERMISSION_DENIED связан с permission, ключом, проектом или включением API. finishReason: SAFETY относится к safety branch. Невалидный file URI связан с ресурсами Files API. Gateway denial принадлежит маршруту или политике прокси.
Лог должен сохранять HTTP status, status string, finish reason, upstream response и gateway response отдельно. Если Google вернул 403, исправляйте ключ, проект или permission. Если отказ пришел от safety, меняйте prompt или маршрут. Если отказ выглядит как file access, проверьте имя файла, URI, MIME type, state и принадлежность проекту.
Повтор по тому же пути сохраняет чистый сигнал
Смысл same-path проверки в том, чтобы не потерять причину. Перед заменой модели, key, endpoint, prompt, provider или input повторите тот же request path.
| Повторный результат | Интерпретация | Действие |
|---|---|---|
| Снова 429 | Квотная ветка стабильна | Backoff, очередь, Batch API или 429 route |
| Снова 503 | Ветка емкости стабильна | Bounded retry, очередь или 503 route |
| Стал 504 | Проявился timeout | Увеличьте timeout или уменьшите нагрузку |
| Успех без изображения | Проявилась форма ответа | Проверяйте parts, inlineData, modality, safety, file |
| Стал 403 или denial | Проявились права, safety или file | Исправьте конкретного владельца |
Меняйте одну переменную за раз. Когда доказана постоянная квотная проблема, можно оценить альтернативные маршруты для Nano Banana 2 при 429.
Часто задаваемые вопросы
503 означает, что Nano Banana API полностью недоступен?
Нет. Один 503 показывает ветку availability или capacity для текущего запроса. Нужен повтор тем же путем и сравнение с другими моделями или endpoint.
Billing исправляет 503?
Billing влияет на квоты и tier, но доказанный 503 не является billing branch. Не смешивайте 429 и 503.
Почему ответ есть, а изображения нет?
Parser мог не обойти все parts, запрос мог не просить image output, генерация могла завершиться safety finish, или input file мог быть недоступен API.
Что первым проверить при request denied?
Сначала HTTP status. Для 403 проверяйте key, project, API enablement и permission. При success с safety finish работайте с prompt или policy. При file branch проверяйте file URI и ownership.
Когда менять модель или provider?
Только после доказанной ветки. Постоянный 429, устойчивый 503, safety limit или gateway policy могут оправдать переключение, но не в первой диагностической итерации.