Gemini API не работает: регион, ключ, лимиты и имя модели

Когда Gemini API не работает, причина почти всегда укладывается в пять пунктов: сервис недоступен в вашем регионе, ключ заблокирован или создан неверно, исчерпан лимит, сервис Google временно перегружен или в запросе неправильное имя модели. Ниже чек-лист в порядке «от дешёвой проверки к дорогой» и таблица ошибок, чтобы за десять минут понять, что именно сломалось.

Мы опираемся на документацию Google (страницы Troubleshooting, Rate limits, Available regions, API key) и на коды ошибок шлюза Zukko. Состояние на 18 октября 2026.

Шаг 1. Проверьте статус сервиса

Если запросы, которые работали час назад, вдруг падают, сначала проверьте статус сервиса: у Google AI Studio есть страница статуса по адресу aistudio.google.com/status (её и ищут по запросу «gemini api status»). Если там инцидент, ваш код ни при чём, и остаётся ждать и ретраить.

Для запросов через шлюз статус провайдера модели виден по ошибке 503: в документации Zukko она означает, что провайдер недоступен или модель выключена (model_disabled).

Шаг 2. Регион и допуск к сервису

Самая частая причина, по которой «Gemini не работает в России»: Gemini API и Google AI Studio работают не везде. России нет в списке поддерживаемых стран на странице Available regions (по состоянию на её обновление 28 апреля 2026). Помимо региона, Google требует возраст 18+ и подтверждение возраста в аккаунте.

Типичные признаки: AI Studio не открывается или сообщает, что сервис недоступен в вашей стране, ключ создать не удаётся, прямые запросы получают отказ по региону. Исправить это настройками клиента нельзя, а схемы обхода мы не рекомендуем. Рабочая альтернатива из России: доступ через шлюз, оплата СБП, картой MasterCard или криптой. Gemini 3.8 Flash и 3.7 Flash вызываются там по OpenAI-формату, подробности в статье Gemini в России через API↗.

Шаг 3. Ключ: неверный, утёкший, ограниченный

По документации Google, у ключей есть несколько особенностей, из-за которых «ключ есть, а не работает»:

• Утёкшие ключи блокируются. Если Google нашёл ваш ключ в открытом доступе (в публичном репозитории, например), он перестаёт работать, а в ответе вы увидите сообщение вроде «Your API key was reported as leaked. Please use another API key.» Решение одно: выпустить новый ключ и больше не хранить его в коде.
• Неограниченные «стандартные» ключи отклоняются. Gemini API отвергает запросы с unrestricted standard keys, а ключи с явными ограничениями продолжают работать. Новые ключи, созданные в AI Studio после 28 мая 2026, по умолчанию создаются как authorization keys, привязанные к сервисному аккаунту.
• Переменная окружения. Клиентские библиотеки Google читают GEMINI_API_KEY или GOOGLE_API_KEY; если заданы обе, приоритет у GOOGLE_API_KEY. Старый ключ в GOOGLE_API_KEY легко перебьёт новый в GEMINI_API_KEY.

С ключом шлюза проще: он начинается с fetch_, показывается один раз при создании, а ответ 401 означает опечатку, пробелы вокруг ключа или отозванный ключ. Подробно про заголовки и форматы — в разделе аутентификации↗.

Шаг 4. Лимиты: 429

Ошибка 429 RESOURCE_EXHAUSTED у Google означает, что вы превысили лимит по запросам в минуту (RPM), входным токенам в минуту (TPM) или запросам в сутки (RPD). Нюансы из документации:

• лимиты считаются на проект, а не на ключ;
• RPD обнуляется в полночь по тихоокеанскому времени;
• на бесплатном уровне лимиты ниже, а у preview-моделей жёстче;
• на платных уровнях добавлены лимиты по расходу за скользящие 10 минут (Tier 1, например, $10 за окно), и превышение тоже даёт 429.

Что делать: снизить частоту, уменьшить контекст и выходные токены, разнести пики по времени, повторять запрос с экспоненциальной паузой и случайным разбросом (jitter), а при постоянном упоре перейти на платный уровень или шлюз.

В Zukko 429 бывает по двум причинам: исчерпан дневной или месячный лимит именно вашего ключа (key_daily_limit_reached, key_monthly_limit_reached) либо ограничение на стороне провайдера модели. Общего rate limit у Zukko нет, так что при 429 сначала откройте настройки ключа и посмотрите, не упёрлись ли вы в собственный лимит в долларах. Подробнее — лимиты ключей и кэш↗.

Шаг 5. Ошибка 503 и перегрузка

Код 503 UNAVAILABLE — временная проблема на стороне сервиса. Документация Google советует делать повторы с экспоненциальной паузой (например, 1, 2, 4 и 8 секунд), добавлять случайный разброс, ограничить число попыток и не повторять клиентские ошибки (400, 402, 403), потому что они говорят о неверном ключе, нулевой предоплате или плохом синтаксисе. Официальные SDK Google делают такие повторы сами.

Минимальная реализация для OpenAI SDK:

import random
import time
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_ваш_ключ")

def ask(prompt, retries=4):
    for attempt in range(retries):
        try:
            r = client.chat.completions.create(
                model="gemini-3.8-flash",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except APIStatusError as e:
            if e.status_code in (429, 503) and attempt < retries - 1:
                time.sleep(2 ** attempt + random.random())
                continue
            raise

print(ask("Ответь одним словом: проверка"))

Если вместо временной перегрузки вы получаете 503 с кодом model_disabled, повторы не помогут: модель выключена, а запрос нужно перенаправить на другую модель из GET /v1/models. То же с 429 key_daily_limit_reached или key_monthly_limit_reached: это лимит вашего ключа, и ждать нужно сброса лимита или поднять его в кабинете. Подробный разбор — ошибка 503 model_disabled↗.

Шаг 6. Неверное имя модели

Опечатка в имени модели даёт 404. В шлюзе Zukko это model_not_found: модели с таким именем нет в каталоге. Частые причины:

• префиксы и суффиксы, которых нет в каталоге (models/gemini-3.8-flash, gemini-3.8-flash-latest, дата в конце);
• имя из документации Google, которого шлюз не поддерживает: в нём доступны gemini-3.8-flash и gemini-3.7-flash;
• старое имя снятой с обслуживания модели.

Список актуальных имён всегда даёт GET https://api.zukko.pro/v1/models. У Google аналог — страница моделей в документации. Проверьте также версию API: у Google часть возможностей доступна только в /v1beta, а не в /v1.

Другие причины «странных» ответов

• Пустой или обрезанный ответ. Если модель рассуждает перед ответом, эти токены могут расходовать лимит выходных токенов. Если max_tokens слишком мал, на сам ответ может не остаться места: увеличьте лимит и посмотрите usage.
• Блокировка по безопасности. В ответе может быть причина блокировки (например, BlockedReason.OTHER или RECITATION). Переформулируйте запрос и проверьте настройки безопасности.
• Параметры не действуют. На странице диагностики Google указано, что у новых моделей (Gemini 3.6 и новее) пользовательские temperature, top_p и top_k игнорируются. Если вы подбираете «креативность» этими ручками, результата не будет.
• Повторы в ответе. Рекомендации Google: добавить в промпт «Be concise» или «Don't repeat yourself», а при необходимости поднять температуру на моделях, где она применяется.

Сводная таблица

Частые вопросы

Почему Gemini не работает в России?

Gemini API и Google AI Studio доступны в ограниченном наборе стран, и России в официальном списке регионов нет. Из России практичнее использовать шлюз: оплата СБП, картой MasterCard или криптой.

Где посмотреть статус Gemini API?

На странице статуса Google AI Studio (aistudio.google.com/status).

Ключ создан, но запросы отклоняются. В чём дело?

Проверьте, не заблокирован ли он как утёкший, не неограниченный ли это «стандартный» ключ и нет ли в окружении другой переменной (GOOGLE_API_KEY приоритетнее GEMINI_API_KEY). Если ничего не помогло, выпустите новый ключ.

Ошибка 429 повторяется постоянно. Как с ней жить?

Уменьшите частоту запросов и размер контекста, добавьте повторы с растущей паузой. Если вы в шлюзе, проверьте дневной и месячный лимит самого ключа: часто 429 приходит именно от него.