Эта страница — troubleshooting для разработчиков: что означают типичные ответы Gemini API, как проверить ключ и квоты и чем API-ошибки отличаются от проблем веб-чата. Базовый how-to по ключу и первому запросу — в Gemini API; здесь фокус на сбоях.
Сначала отделите API от веб-чата
- Веб Gemini не открывается — регион, вход, сеть: не работает, вход.
- HTTP-ошибка из SDK/REST — ключ, проект, модель, квота: оставайтесь на этой странице.
Путать пароль Google-аккаунта с API-ключом — частая причина «всё сломалось после смены пароля» при живом ключе.
401 — неверный или отозванный ключ
- Сверьте ключ с AI Studio (без пробелов и кавычек в .env).
- Убедитесь, что подставляете ключ в правильный заголовок/параметр SDK.
- Создайте новый ключ, если старый могли засветить в репозитории.
- Проверьте, что приложение читает нужный env в prod, а не dev-заглушку.
403 — доступ запрещён
Частые причины:
- API не включён для проекта Google Cloud / AI Studio.
- Ключ от другого проекта.
- Ограничения по IP/referrer, если вы их настроили.
- Региональные или организационные политики.
- Модель или метод недоступны для данного ключа.
Чеклист: проект → включённые API → ключ → имя модели → минимальный curl/SDK-запрос. Контекст доступа из РФ: Gemini в России.
429 — квота и rate limit
- Снизьте частоту запросов, добавьте экспоненциальный backoff.
- Проверьте RPM/TPM (или аналогичные метрики) в консоли.
- Разведите batch и интерактивные вызовы по разным ключам/проектам.
- Не дергайте тяжёлую Pro-модель там, где хватает Flash — Flash, Pro.
Цифры квот намеренно не выдумываем: они зависят от проекта и тарифа. Смотрите панель usage.
400 и ошибки схемы запроса
- Неверное имя модели (опечатка, устаревший id).
- Пустой prompt или неверный формат multipart для файлов.
- Слишком большой контекст для выбранной модели.
- Неподдерживаемая комбинация параметров generationConfig.
Мультимодальность и видео — отдельная тема: анализ видео, картинки — для изображений.
5xx и сетевые сбои
Повторите запрос с jitter, проверьте DNS/прокси, логируйте request id если SDK его отдаёт. Отличайте таймаут клиента от ответа сервера.
Безопасный минимум для продакшена
- Секреты вне Git; ротация при утечке.
- Алерты на долю 401/403/429.
- Идемпотентность и очередь для массовой генерации.
- Раздельные ключи на среды.
По состоянию на сентябрь 2026 детали консолей Google могут менять названия пунктов меню — ориентируйтесь на коды ошибок и usage, не на чужие скриншоты.
FAQ
Почему 403 сразу после создания ключа?
Часто не активирован API или выбран не тот проект. Пройдите чеклист выше.
Лимиты free в API такие же, как в чате?
Нет, это разные доступы. Чат: бесплатно; API — квоты проекта.
Нужна ли подписка Gemini для API?
Не путайте веб-подписку с биллингом Cloud/AI Studio — подписка vs API.
Как понять, что упёрлись в квоту, а не в баг кода?
Смотрите тело ответа 429 и график usage; минимальный запрос «hello» вне вашего бизнес-кода.
Ошибка только на русском тексте?
Проверьте UTF-8 и экранирование JSON. Язык промпта обычно ни при чём.
Где общий обзор возможностей, если API тут ни при чём?
Что умеет Gemini — продуктовый хаб.
