Ошибки Gemini API: как разобраться с 429, 403, 400 и 5xx

Если Gemini API возвращает ошибку, сначала прочитайте сообщение в теле ответа и установите, какой запрос не прошёл. Код 429 не всегда означает, что достаточно подождать несколько секунд: может закончиться суточная квота. Код 403 не всегда связан с неверным ключом: доступ может быть ограничен для всего проекта. При 400 и 404 обычно нужно исправить запрос или ресурс; при временных 500, 503 и 504 допустимы несколько попыток с растущей задержкой, после которых приложение должно остановиться.

Это руководство относится к Gemini Developer API, в том числе к вызовам generateContent. Ошибки приложения Gemini, Gemini CLI и корпоративных сервисов могут иметь другие причины и условия доступа. Названия ошибок тоже зависят от интерфейса: документация Interactions API описывает строковые значения error.code, тогда как в ответах других методов и исключениях SDK встречаются числовой код и статусы вроде RESOURCE_EXHAUSTED. Не стройте обработчик на предположении, что у всех ответов одинаковый JSON. Справочник ошибок Gemini API.

Найдите свой случай по коду и сообщению

Таблица задаёт порядок проверки, но не заменяет сообщение сервера. В частности, для Interactions API официально различаются rate_limit_exceeded и quota_exceeded при HTTP 429. Описание кодов и причин.

Перед изменениями сохраните время сбоя с часовым поясом, метод API, модель, версию SDK, HTTP-код, очищенное сообщение и идентификатор запроса, если сервер его вернул. Не записывайте в общие логи API-ключи, заголовки авторизации, содержимое конфиденциальных документов и URL с секретными параметрами. Если работает несколько процессов, установите, к какому проекту относится каждый: иначе легко сравнить ошибку одного проекта со статистикой другого.

Ошибка 429: выясните, какой лимит закончился

У Gemini Developer API есть отдельные ограничения на запросы в минуту — RPM, входные токены в минуту — TPM и запросы в сутки — RPD. Превышения одного применимого ограничения достаточно для отказа. Лимиты действуют на проект, а не на ключ; дополнительные ключи того же проекта не добавляют квоту. Актуальные значения для доступных моделей и своего уровня смотрите в Google AI Studio через ссылку на активные лимиты в официальном руководстве.

Проверяйте сообщение ошибки и активные ограничения в таком порядке:

1. RPM: много коротких запросов за небольшой промежуток. Уменьшите частоту отправки и число параллельных задач; поставьте запросы в общую очередь, если их отправляют несколько работников.
2. TPM: запросов немного, но каждый несёт большой контекст. Уберите ненужные данные или распределите обработку по времени. Уменьшение числа запросов само по себе не уменьшает число входных токенов.
3. RPD: дневная квота исчерпана. Остановите повторные попытки до сброса либо рассмотрите увеличение доступной квоты. RPD сбрасывается в полночь по тихоокеанскому времени; для расписания используйте часовой пояс America/Los_Angeles, учитывающий переход на летнее время.
4. Ограничение расходов за короткое окно: у некоторых аккаунтов действует дополнительный предел расходов за скользящие десять минут. Он зависит от условий аккаунта и может объяснить 429 при невысоких RPM и TPM. Проверьте применимость по описанию spend-based rate limits.

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

Почему в статистике почти ноль, а API уже возвращает 429

Низкий показатель на панели ещё не доказывает сбой учёта. Сопоставьте проект, модель, период и метрику с конкретным запросом. Посмотрите, не ограничен ли доступ проекта и не сработал ли другой тип лимита. Отдельная особенность новых authorization keys: вызовы с такими ключами не попадают в метрики использования сервисного аккаунта Google Cloud. Это не означает, что статистика Gemini в AI Studio отсутствует вообще. Различия типов ключей.

Если причина не видна, сохраните очищенный ответ и данные воспроизведения, затем обратитесь в поддержку. Универсального срока «подождите 15–30 минут, и всё восстановится» нет. Не запускайте бесконечный повтор, чтобы проверить эту гипотезу.

Как выбрать задержку и когда нужен платный уровень

Настраивайте очередь по фактическим лимитам проекта. Например, при условном бюджете 12 запросов в минуту равномерная отправка одного запроса каждые 5 секунд даёт 12 запросов за 60 секунд. Это расчёт нагрузки, а не заявленная квота Gemini и не гарантия отсутствия 429: остаются TPM, суточный предел, другие процессы и правила учёта окна. Универсальная задержка в 100–300 миллисекунд не решает все эти задачи.

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

Ошибка 403: проверьте ключ, проект и условия доступа

При 403 идите от фактических учётных данных к состоянию проекта. Создавать новый ключ наугад — плохой первый шаг: ограничение проекта сохранится и с новым ключом.

Убедитесь, что процесс использует ожидаемый ключ. В стандартном автоматическом выборе переменных окружения SDK отдаёт приоритет GOOGLE_API_KEY, если одновременно задана GEMINI_API_KEY. Проверяйте имена переменных и их источник, не печатая значения. В примерах ниже ключ передаётся явно из GEMINI_API_KEY, чтобы исключить эту неоднозначность.

Проверьте тип ключа и его ограничения. С 28 мая 2026 года новые ключи AI Studio создаются как authorization keys, привязанные к сервисному аккаунту. Неограниченные standard keys отклоняются; standard keys с явно заданными ограничениями продолжают работать. Поэтому совет «снимите все ограничения ключа» может усугубить проблему. Используйте ограничения, предназначенные для Gemini API. При сообщении об утечке или блокировке ключ нужно заменить и убрать из места утечки. Официальное руководство по ключам.

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

Проверьте фактический регион использования. На дату обновления статьи Россия отсутствует в списке поддерживаемых регионов Gemini API. Русский язык интерфейса или кода ничего не говорит о местоположении разработчика и сервера. Сопоставляйте условия с реальным местом работы; включение оплаты само по себе не устраняет региональное ограничение.

Если ошибка возникает только при обращении к файлу, переходите к проверке ресурса ниже. Отказ в доступе к одному файлу и запрет генерации для проекта требуют разных действий.

Ошибки 400 и 404: сократите запрос и проверьте ресурсы

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

Параметры должны соответствовать конкретной модели и версии API. Не переносите настройки temperature, top_p, top_k из старого примера без проверки: нынешняя документация описывает разное поведение для разных поколений моделей. Значение temperature=1.0 не является универсальным исправлением ошибки 400. Начните со значений по умолчанию и проверьте ограничения параметров выбранной модели.

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

Список моделей открывается, но генерация не работает

Успешный models.list не доказывает, что проект допущен к генерации или что биллинг исправен. Google прямо отмечает, что этот метод может вернуть 200, не проверяя соответствующие условия. Поэтому разделите две проверки: доступ к списку моделей и отдельный небольшой вызов генерации. Второй вызов расходует ресурсы и может быть платным. Пояснение Google о проверке проекта.

Запрос перестал работать со старым файлом

Файлы, загруженные через Files API, автоматически удаляются через 48 часов. Если приложение хранит ссылку дольше, проверьте наличие файла через files.get, его принадлежность проекту и доступ к нему; при необходимости загрузите исходный файл заново и обновите ссылку. Не удаляйте обязательное вложение из рабочего запроса только ради успешного HTTP-ответа: результат уже не будет выполнять исходную задачу. Срок хранения файлов.

500, 503 и 504: ограничьте повторы и отделите сбой от тяжёлого запроса

Для временных 500 и 503 разумно повторить запрос с увеличивающейся задержкой и небольшим случайным разбросом. Проверьте официальную страницу состояния Gemini, но отсутствие опубликованного инцидента не исключает ошибку конкретного вызова. Если после нескольких попыток сбой остаётся, прекратите цикл и сохраните диагностику. Такой подход соответствует рекомендациям Google по повторным запросам.

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

При 504 различайте ответ сервера об истечении срока обработки и тайм-аут вашего HTTP-клиента. Увеличение клиентского тайм-аута помогает только тогда, когда первым сдаётся клиент; оно не снимает серверное ограничение. Потеря ответа также не доказывает, что сервер ничего не обработал. Учитывайте это перед повтором дорогой операции или действия с побочными эффектами.

Ограниченные повторы на Python и Node.js

Для новых интеграций используйте google-genai и @google/genai. Старые google-generativeai и @google/generative-ai больше не являются актуальной основой для новых примеров; Google описывает переход в руководстве по SDK.

Ниже — небольшие программы для проверки генерации с уже выбранной доступной моделью. Задайте GEMINI_API_KEY и GEMINI_MODEL в окружении процесса через свой механизм работы с секретами. Не вставляйте ключ в исходный файл. Запуск с настоящими учётными данными выполняет реальный API-вызов.

Политика примеров намеренно узкая: не более трёх попыток всего, повторы только при 500, 503 и 504. Ошибка 429 сразу передаётся вызывающему коду, чтобы сначала определить вид лимита. Внешнего цикла поверх SDK нет: два уровня повторов могут незаметно увеличить число запросов. timeout задаётся в миллисекундах, задержки — в секундах; 30 секунд в примере относятся к запросу, а не ко всей операции с повторами. Параметры Python SDK и параметры повторов JavaScript SDK.

Python

Установите пакет командой python -m pip install google-genai, сохраните код в check_gemini.py и запустите python check_gemini.py.

import os
from google import genai
from google.genai import errors, types


def main():
    options = types.HttpOptions(
        timeout=30_000,
        retry_options=types.HttpRetryOptions(
            attempts=3,
            initial_delay=1.0,
            max_delay=8.0,
            exp_base=2.0,
            jitter=1.0,
            http_status_codes=[500, 503, 504],
        ),
    )
    with genai.Client(
        api_key=os.environ["GEMINI_API_KEY"],
        http_options=options,
    ) as client:
        try:
            response = client.models.generate_content(
                model=os.environ["GEMINI_MODEL"],
                contents="Ответь одним словом: готово.",
            )
        except errors.APIError as exc:
            # Подробности сохраняйте только после удаления секретных данных.
            print(f"Вызов не выполнен. Код API: {exc.code}")
            raise SystemExit(1) from None
        if not response.text:
            raise SystemExit("Текст не получен: проверьте метаданные ответа.")
        print(response.text)


if __name__ == "__main__":
    main()

Node.js

Установите пакет командой npm install @google/genai, сохраните код в check-gemini.mjs и запустите node check-gemini.mjs.

import { GoogleGenAI } from "@google/genai";

async function main() {
  const apiKey = process.env.GEMINI_API_KEY;
  const model = process.env.GEMINI_MODEL;
  if (!apiKey || !model) {
    throw new Error("Задайте GEMINI_API_KEY и GEMINI_MODEL.");
  }
  const ai = new GoogleGenAI({
    apiKey,
    httpOptions: {
      timeout: 30_000,
      retryOptions: {
        attempts: 3,
        initialDelay: 1,
        maxDelay: 8,
        expBase: 2,
        jitter: 1,
        httpStatusCodes: [500, 503, 504],
      },
    },
  });
  try {
    const response = await ai.models.generateContent({
      model,
      contents: "Ответь одним словом: готово.",
    });
    if (!response.text) {
      throw new Error("Текст не получен: проверьте метаданные ответа.");
    }
    console.log(response.text);
  } catch (error) {
    // Не выводим ответ целиком: он может содержать данные запроса.
    console.error("Вызов не выполнен. Код API:", error.status ?? "не указан");
    process.exitCode = 1;
  }
}

main().catch(() => {
  console.error("Не удалось подготовить вызов. Проверьте настройки окружения.");
  process.exitCode = 1;
});

Примеры проверены локально с google-genai 2.33.0 и @google/genai 2.31.0 на подменённых HTTP-ответах, без обращения к Google. Такая проверка подтверждает создание запросов и работу заданного числа попыток, но не доступ вашего проекта, текущую квоту или успешность реальной генерации. После настоящего запуска признаком успеха будет полученный текст; отсутствие текста требует отдельной проверки метаданных ответа, а не автоматического повторения вслепую.

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

Когда прекращать попытки и что передать в поддержку

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

Ошибка не всегда означает отсутствие расхода квоты. В FAQ по биллингу Google указывает, что запросы с ошибками 400 и 500 не оплачиваются по токенам, но учитываются в квоте. Это утверждение нельзя автоматически переносить на любой тайм-аут, ошибку или повторную генерацию. Поэтому бесконечный цикл не только мешает диагностике — он может ещё и уменьшать доступный запас запросов.