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

> При ошибке Gemini API сначала проверьте тело ответа: 429 может означать исчерпанную квоту, а 403 — ограничение проекта. Порядок диагностики и примеры на Python и Node.js.

- Source: https://www.aifreeapi.com/ru/posts/gemini-api-error-troubleshooting-guide
- Language: ru
- Published: 2026-03-17
- Updated: 2026-10-28
- Publisher: AI Free API (https://www.aifreeapi.com)

Если 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](https://ai.google.dev/gemini-api/docs/api-errors).

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

![Схема разбора ошибок Gemini API](https://www.aifreeapi.com/posts/ru/gemini-api-error-troubleshooting-guide/img/error-decision-tree.webp)

| Что вернул API | Что проверить первым | Когда повторять запрос |
| --- | --- | --- |
| 400: неверный запрос или невыполненное условие | Поля запроса, доступность функции, условия доступа | После исправления причины |
| 401: ошибка аутентификации | Какие учётные данные фактически использует процесс | После исправления учётных данных |
| 402: закончились средства Prepay | Баланс и состояние оплаты | После восстановления возможности оплаты |
| 403: отказ в доступе | Ключ, его ограничения, проект, права и биллинг | После восстановления доступа |
| 404: ресурс не найден | Точное имя модели или файла, версия API, доступность ресурса | После исправления ссылки или выбора доступного ресурса |
| 429: превышен лимит | Какая именно квота и за какой период исчерпана | При кратковременном ограничении — с задержкой; при суточной квоте — после сброса или увеличения |
| 500, 503, 504 | Повторяется ли сбой на небольшом запросе, есть ли инцидент | Ограниченное число раз, если сбой временный |
| 501: функция не реализована | Поддерживает ли выбранный интерфейс эту операцию | После изменения операции, а не по таймеру |

Таблица задаёт порядок проверки, но не заменяет сообщение сервера. В частности, для Interactions API официально различаются `rate_limit_exceeded` и `quota_exceeded` при HTTP 429. [Описание кодов и причин](https://ai.google.dev/gemini-api/docs/api-errors).

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

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

У Gemini Developer API есть отдельные ограничения на запросы в минуту — RPM, входные токены в минуту — TPM и запросы в сутки — RPD. Превышения одного применимого ограничения достаточно для отказа. Лимиты действуют **на проект, а не на ключ**; дополнительные ключи того же проекта не добавляют квоту. Актуальные значения для доступных моделей и своего уровня смотрите в [Google AI Studio](https://aistudio.google.com/) через ссылку на активные лимиты в [официальном руководстве](https://ai.google.dev/gemini-api/docs/rate-limits).

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

1. **RPM:** много коротких запросов за небольшой промежуток. Уменьшите частоту отправки и число параллельных задач; поставьте запросы в общую очередь, если их отправляют несколько работников.
2. **TPM:** запросов немного, но каждый несёт большой контекст. Уберите ненужные данные или распределите обработку по времени. Уменьшение числа запросов само по себе не уменьшает число входных токенов.
3. **RPD:** дневная квота исчерпана. Остановите повторные попытки до сброса либо рассмотрите увеличение доступной квоты. RPD сбрасывается в полночь по тихоокеанскому времени; для расписания используйте часовой пояс `America/Los_Angeles`, учитывающий переход на летнее время.
4. **Ограничение расходов за короткое окно:** у некоторых аккаунтов действует дополнительный предел расходов за скользящие десять минут. Он зависит от условий аккаунта и может объяснить 429 при невысоких RPM и TPM. Проверьте применимость по [описанию spend-based rate limits](https://ai.google.dev/gemini-api/docs/rate-limits#spend-based-rate-limits).

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

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

Низкий показатель на панели ещё не доказывает сбой учёта. Сопоставьте проект, модель, период и метрику с конкретным запросом. Посмотрите, не ограничен ли доступ проекта и не сработал ли другой тип лимита. Отдельная особенность новых authorization keys: вызовы с такими ключами не попадают в метрики использования сервисного аккаунта Google Cloud. Это не означает, что статистика Gemini в AI Studio отсутствует вообще. [Различия типов ключей](https://ai.google.dev/gemini-api/docs/api-key).

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

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

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

Платный уровень стоит рассматривать, когда подтверждено, что текущая квота не подходит вашей нагрузке. Сначала проверьте доступные пределы и условия своего проекта. Подключение биллинга означает возможность платного потребления; оно не обещает определённый множитель квоты, доступность любой модели или отсутствие отказов. Google отдельно предупреждает, что указанная квота не гарантирует доступную ёмкость сервиса. [Правила лимитов](https://ai.google.dev/gemini-api/docs/rate-limits).

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

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

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

**Проверьте тип ключа и его ограничения.** С 28 мая 2026 года новые ключи AI Studio создаются как authorization keys, привязанные к сервисному аккаунту. Неограниченные standard keys отклоняются; standard keys с явно заданными ограничениями продолжают работать. Поэтому совет «снимите все ограничения ключа» может усугубить проблему. Используйте ограничения, предназначенные для Gemini API. При сообщении об утечке или блокировке ключ нужно заменить и убрать из места утечки. [Официальное руководство по ключам](https://ai.google.dev/gemini-api/docs/api-key).

**Прочитайте сообщение о проекте и биллинге.** Не каждый проект имеет право на бесплатный уровень. Для ограниченного проекта может потребоваться активный платёжный аккаунт, но платные вызовы не превращаются от этого в бесплатные. При приостановке проекта или платёжного аккаунта следуйте процедуре восстановления, указанной Google; повторная генерация ключа этого не исправляет. [Диагностика ограничений проекта](https://ai.google.dev/gemini-api/docs/troubleshooting#project-restricted-or-unavailable).

**Проверьте фактический регион использования.** На дату обновления статьи Россия отсутствует в [списке поддерживаемых регионов Gemini API](https://ai.google.dev/gemini-api/docs/available-regions). Русский язык интерфейса или кода ничего не говорит о местоположении разработчика и сервера. Сопоставляйте условия с реальным местом работы; включение оплаты само по себе не устраняет региональное ограничение.

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

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

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

Параметры должны соответствовать конкретной модели и версии API. Не переносите настройки `temperature`, `top_p`, `top_k` из старого примера без проверки: нынешняя документация описывает разное поведение для разных поколений моделей. Значение `temperature=1.0` не является универсальным исправлением ошибки 400. Начните со значений по умолчанию и [проверьте ограничения параметров выбранной модели](https://ai.google.dev/gemini-api/docs/troubleshooting#check-your-api-calls-for-model-parameter-errors).

Для 404 сверьте точный идентификатор модели с [текущим каталогом](https://ai.google.dev/gemini-api/docs/models), доступом проекта и [правилами жизненного цикла моделей](https://ai.google.dev/gemini-api/docs/deprecations). Старое рабочее имя не гарантирует, что модель доступна сейчас или новому проекту. Выбирайте замену по нужным возможностям, а затем проверяйте запрос с её параметрами; механическая подстановка исторической модели из чужого примера может оставить ошибку.

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

Успешный `models.list` не доказывает, что проект допущен к генерации или что биллинг исправен. Google прямо отмечает, что этот метод может вернуть 200, не проверяя соответствующие условия. Поэтому разделите две проверки: доступ к списку моделей и отдельный небольшой вызов генерации. Второй вызов расходует ресурсы и может быть платным. [Пояснение Google о проверке проекта](https://ai.google.dev/gemini-api/docs/troubleshooting#project-or-billing-account-policy-suspension).

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

Файлы, загруженные через Files API, автоматически удаляются через 48 часов. Если приложение хранит ссылку дольше, проверьте наличие файла через `files.get`, его принадлежность проекту и доступ к нему; при необходимости загрузите исходный файл заново и обновите ссылку. Не удаляйте обязательное вложение из рабочего запроса только ради успешного HTTP-ответа: результат уже не будет выполнять исходную задачу. [Срок хранения файлов](https://ai.google.dev/gemini-api/docs/files#delete-uploaded-files).

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

Для временных 500 и 503 разумно повторить запрос с увеличивающейся задержкой и небольшим случайным разбросом. Проверьте [официальную страницу состояния Gemini](https://aistudio.google.com/status), но отсутствие опубликованного инцидента не исключает ошибку конкретного вызова. Если после нескольких попыток сбой остаётся, прекратите цикл и сохраните диагностику. Такой подход соответствует [рекомендациям Google по повторным запросам](https://ai.google.dev/gemini-api/docs/troubleshooting#retry-strategy).

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

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

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

![Иллюстрация повторных запросов с увеличивающейся задержкой](https://www.aifreeapi.com/posts/ru/gemini-api-error-troubleshooting-guide/img/retry-strategy.webp)

Для новых интеграций используйте `google-genai` и `@google/genai`. Старые `google-generativeai` и `@google/generative-ai` больше не являются актуальной основой для новых примеров; Google описывает переход в [руководстве по SDK](https://ai.google.dev/gemini-api/docs/libraries).

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

Политика примеров намеренно узкая: **не более трёх попыток всего**, повторы только при 500, 503 и 504. Ошибка 429 сразу передаётся вызывающему коду, чтобы сначала определить вид лимита. Внешнего цикла поверх SDK нет: два уровня повторов могут незаметно увеличить число запросов. `timeout` задаётся в миллисекундах, задержки — в секундах; 30 секунд в примере относятся к запросу, а не ко всей операции с повторами. [Параметры Python SDK](https://googleapis.github.io/python-genai/) и [параметры повторов JavaScript SDK](https://googleapis.github.io/js-genai/release_docs/interfaces/types.HttpRetryOptions.html).

### Python

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

```python
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`.

```javascript
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 по биллингу](https://ai.google.dev/gemini-api/docs/billing#am-i-charged-for-failed-requests) Google указывает, что запросы с ошибками 400 и 500 не оплачиваются по токенам, но учитываются в квоте. Это утверждение нельзя автоматически переносить на любой тайм-аут, ошибку или повторную генерацию. Поэтому бесконечный цикл не только мешает диагностике — он может ещё и уменьшать доступный запас запросов.