Ошибок Gemini API на вид много, но при разборе почти все сводятся к четырём классам: не та личность, не тот адрес, не хватает квоты, сеть не доходит. Собственно проблемы модели встречаются реже.

Ниже ошибки разобраны по кодам и дан порядок диагностики, начиная с минимального запроса. При сбое сначала сохраните полный JSON ошибки, затем проверяйте по порядку — не меняйте одновременно ключ, адрес и модель.

Примечание: Google и Gemini — товарные знаки соответствующих правообладателей. Примеры отражают распространённые формы интерфейса на октябрь 2026 года; версии интерфейса, квоты и региональная политика определяются официальной документацией и страницей цены на модели.

1. Сначала научитесь читать тело ошибки

Ошибки Google API обычно возвращаются в JSON, где важны три поля:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code — HTTP-код, status — машиночитаемый тип ошибки, message часто содержит конкретную причину, а в details может быть ID квоты и рекомендуемое время повтора. Смотрите все три: по одному «429» не понять, исчерпан минутный лимит или дневная квота.

Код Частый status Общее направление
401 UNAUTHENTICATED Ключ отсутствует, недействителен или передан не туда
403 PERMISSION_DENIED Проект не включён, нет прав или ограничение по региону
404 NOT_FOUND Неверное имя модели, путь или версия интерфейса
429 RESOURCE_EXHAUSTED Превышены скорость, параллелизм или квота
400 INVALID_ARGUMENT / FAILED_PRECONDITION Ошибка параметров, регион не поддерживается, не выполнены условия
500/503 INTERNAL / UNAVAILABLE Временный сбой провайдера, обычно помогает повтор с задержкой

2. 401: ключ недействителен или выбран не тот способ аутентификации

Суть 401 — «сервер не признаёт вашу личность». Частые причины:

  • В запросе вообще нет ключа или переменная окружения пуста.
  • В нативном интерфейсе использован Authorization вместо x-goog-api-key.
  • В OpenAI-совместимом интерфейсе использован x-goog-api-key вместо Authorization: Bearer.
  • Вокруг ключа пробелы или переводы строки, при копировании попали кавычки.
  • Ключ удалён, ротирован или проект отключён.
  • Ключ шлюза отправлен на официальный адрес Google или наоборот.
  • На ключ наложены ограничения API, не разрешающие вызов Gemini API.

Сначала проверьте минимальным запросом:

export GEMINI_API_KEY="ваш-ключ"

# Нативный интерфейс Gemini
curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-модели>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Ответь только OK"}]}]}'

# OpenAI-совместимый интерфейс
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID-модели>","messages":[{"role":"user","content":"Ответь только OK"}]}'

Две команды соответствуют двум схемам аутентификации. Какая проходит, к той системе и относятся ваш ключ и адрес; при смешивании 401 означает не сломанный ключ, а неверную комбинацию.

3. 404: неверное имя модели, путь или версия

404 не обязательно означает «модели не существует». Частые случаи:

  1. ID модели указан с ошибкой или взято отображаемое имя из консоли вместо идентификатора API.
  2. Модель не относится к текущей версии API: например, доступная только в новой версии отправлена на старый путь.
  3. В Base URL лишний или пропущенный /v1 либо /v1beta; после склейки путь ведёт в никуда.
  4. В конце адреса остался слэш, и клиент добавил путь ещё раз.
  5. При вызове через шлюз модель не включена в текущую группу или тариф.
  6. Чат-интерфейс использован для генерации изображений или другого специализированного интерфейса.

Начните с вывода доступных моделей для текущего ключа:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Если нужная модель в списке есть, сверяйте путь запроса; если нет — сначала решите вопрос доступа или прав. При вызове через шлюз ориентируйтесь на ID модели и Base URL из документации шлюза, не подставляйте официальные имена напрямую.

4. 429: сначала отличите лимит от исчерпанной квоты

429 ошибочно трактуют чаще всего. Он включает как минимум три ситуации:

Тип Типичный признак Направление действий
Минутный лимит Высокий параллелизм в коротком окне, ошибки за несколько секунд Снизить параллелизм, повторить с задержкой
Исчерпана дневная квота Дневной объём достигнут, ошибки продолжаются Дождаться сброса, поднять квоту или сменить схему
Квота проекта Несколько сервисов делят проект и конкурируют Разделить проекты и ключи, выделить квоты

В details обычно указаны ID квоты и рекомендуемое время повтора. Не отправляйте запрос повторно сразу после 429: шторм повторов ухудшит ситуацию. Установите зависимость pip install requests. Рабочая логика задержек:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<ID-модели>:generateContent"
    headers = {
        "x-goog-api-key": "ваш-ключ",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("Попытки исчерпаны")

Повторы снимают временную перегрузку, но не исчерпанную квоту. В продакшене нужны также тайм-ауты, предохранитель и резервная модель, иначе один 429 утянет всю цепочку.

5. Региональные ограничения: почему прямое подключение из Китая не работает

Gemini API доступен только в части стран и регионов. Когда выход запроса попадает в неподдерживаемый регион, типичны три проявления:

  • Тайм-аут соединения или сбой TLS-рукопожатия — обычно сетевой путь недоступен.
  • Ответ 400 FAILED_PRECONDITION с текстом вида location is not supported.
  • Ответ 403 PERMISSION_DENIED, связанный с проектом, биллингом или региональными правами.

Здесь легко перепутать два понятия: регион регистрации аккаунта и регион выхода запроса. Даже если аккаунт доступен, сервер в неподдерживаемом регионе может получить отказ; и наоборот, локальный прокси открывает веб-страницу, но это не значит, что API-запрос идёт тем же маршрутом.

Рекомендуемый порядок:

  1. Определите, откуда уходит запрос — с локальной машины, из контейнера или с сервера, и найдите реальный IP выхода.
  2. Сверьте регион выхода с официальным списком поддерживаемых.
  3. Проверьте регион облачного сервера и при необходимости перейдите в поддерживаемый.
  4. Если бизнес в основном в Китае, оцените подключение через соответствующий требованиям шлюз с единой обработкой сети и биллинга.
  5. Не считайте «смену IP» единственным решением: сначала проверьте условия обслуживания и местное законодательство.

6. Другие частые ошибки

Симптом Частая причина Действие
400 INVALID_ARGUMENT Ошибка структуры JSON, порядок ролей, неподдерживаемый формат изображения Начать с минимального запроса и добавлять поля по одному
400 FAILED_PRECONDITION Регион не поддерживается, биллинг не подключён, нет условия Проверить регион, биллинг и состояние проекта
403 PERMISSION_DENIED API не включён, ограничения ключа, нехватка прав проекта Включить в консоли и проверить права
500 INTERNAL Внутренняя ошибка провайдера Повтор с задержкой, записать request ID
503 UNAVAILABLE Перегрузка или обслуживание Повтор с задержкой, переключить резервную модель
Ответ есть, содержимого нет Сработала политика безопасности, вывод обрезан Смотреть blockReason и finishReason
Вывод оборвался Достигнут максимум выходных токенов Поднять лимит или сократить вход

«Ответ есть, а содержимого нет» часто принимают за сбой, хотя это фильтр безопасности или ограничение длины. Сначала посмотрите promptFeedback.blockReason, finishReason и usageMetadata, затем решайте, менять промпт или параметры.

7. Рекомендуемый порядок диагностики

  1. Сохраните полный JSON ошибки, время запроса, ID модели и request ID.
  2. Отправьте минимальный запрос через curl, исключив влияние клиента и SDK.
  3. Сверьте три вещи: Base URL, заголовок аутентификации и ID модели.
  4. Переключитесь на заведомо доступную модель, чтобы понять, проблема в модели или в канале.
  5. Проверьте квоты, биллинг и состояние проекта, различите 429 и 403.
  6. Уточните регион выхода запроса и сетевой путь.
  7. В последнюю очередь проверяйте настройки клиента, прокси и логику повторов в коде.

Меняйте по одной переменной за раз. Иначе даже после восстановления непонятно, какой шаг помог, и в следующий раз вы наступите на те же грабли.

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

Чем отличаются 401 и 403?

401 — «личность не подтверждена»: сначала проверьте ключ, заголовок аутентификации и соответствие адреса. 403 — «личность подтверждена, но прав нет»: проверьте, включён ли API, права проекта, ограничения ключа и региональную политику.

Достаточно ли при 429 подождать несколько минут?

Зависит от типа квоты. Минутный лимит после задержки обычно восстанавливается; исчерпанная дневная квота требует сброса или повышения. Сначала прочитайте ID квоты и рекомендацию по повтору в теле ошибки, не отправляйте запросы слепо.

Решается ли региональное ограничение сменой IP?

Не обязательно. Важны реальный регион выхода, состояние аккаунта и условия обслуживания. Для корпоративных сценариев надёжнее развернуться в поддерживаемом регионе или подключиться через соответствующий требованиям шлюз.

Официальный адрес работает, а через шлюз возвращается 404 — чья это проблема?

Сначала сверьте Base URL и ID модели шлюза. Имена моделей, пути и доступный набор могут отличаться от официальных, поэтому официальный запрос нельзя переносить напрямую. Заменяйте по минимальному примеру из документации шлюза.

Как не раздуть затраты повторами?

Задайте максимальное число повторов, экспоненциальную задержку и тайм-ауты; обрабатывайте 429 отдельно; добавляйте дедупликацию для неидемпотентных запросов; на стороне шлюза установите бюджет и оповещения.

Что дальше

Ключ к диагностике ошибок Gemini — сначала разделить «аутентификацию, путь, квоту и сеть», затем проверить каждый пункт минимальным запросом. Если нужен единый вход и меньше неопределённости при прямом доступе из Китая, зарегистрируйтесь в ZSQH AI Gateway. Модели, квоты и цены — на странице цены на модели.

Читайте также: