Gemini API 429 `RESOURCE_EXHAUSTED`: квоты, тарифные уровни и повторы

Q: Где посмотреть мои лимиты Gemini API?

Откройте страницу Rate Limit в Google AI Studio (aistudio.google.com/rate-limit). На ней показаны действующие лимиты для вашего проекта и уровня по каждой модели. На странице Projects указан текущий уровень использования каждого проекта, а на странице Usage — недавнее потребление.

Ваши вызовы Gemini работали нормально, а затем начали падать с HTTP 429 и статусом RESOURCE_EXHAUSTED. На этой странице разобрано, в какой именно лимит вы уперлись, почему добавление новых API-ключей не помогает, чем отличаются бесплатный и платные уровни и как настроить повторные попытки, чтобы не усугубить ситуацию.

Краткий ответ

Ошибка 429 RESOURCE_EXHAUSTED означает, что ваш проект Google Cloud, а не конкретный API-ключ, превысил один из лимитов для этой модели: число запросов в минуту (RPM), входных токенов в минуту (TPM), запросов в день (RPD) или лимит по расходам. Повторяйте запросы с экспоненциальной задержкой и джиттером (jitter), выжидая как минимум время из поля retryDelay, если оно пришло в теле ошибки. Затем проверьте свои текущие лимиты на странице Rate Limit в AI Studio. Чтобы решить проблему насовсем, снизьте частоту или размер запросов либо переведите проект на более высокий уровень использования, привязав платежный аккаунт.

Симптомы и что означает эта ошибка

В generateContent API ошибка превышения квоты 429 выглядит так. Пример ниже привел пользователь в тикете googleapis/python-genai#1427:

json

{
  "error": {
    "code": 429,
    "message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [{ "description": "Learn more about Gemini API quotas", "url": "https://ai.google.dev/gemini-api/docs/rate-limits" }]
      }
    ]
  }
}

Некоторые ответы 429 также содержат рекомендуемое время ожидания в блоке google.rpc.RetryInfo, как показано в python-genai#1875:

json

{ "@type": "type.googleapis.com/google.rpc.RetryInfo", "retryDelay": "53s" }

В справочнике по ошибкам generateContent от Google код 429 описывается так: «Вы превысили один из лимитов частоты запросов API (RPM, TPM, RPD, расходы и т. д.)». Если вы используете более новый Interactions API, поле code прямо указывает, какой именно лимит сработал:

`code` в Interactions API	Значение
`rate_limit_exceeded`	Поминутный или посекундный лимит запросов или токенов
`quota_exceeded`	Дневная квота
`too_many_requests`	Слишком много запросов за короткий промежуток времени

Не путайте эту ошибку со смежными кодами:

402 RESOURCE_EXHAUSTED, "Your Prepay credit balance is depleted." Строка статуса та же, но HTTP-код другой. Все ключи на этом платежном аккаунте перестают работать, пока вы не пополните баланс. Google указывает, что повторять такие запросы не нужно. Подробнее см. в статье Недостаточная квота и ошибки оплаты 402.
503 UNAVAILABLE. Сервису Google временно не хватает мощностей. Это не ваша квота, поэтому здесь помогает задержка перед повтором, а в качестве временного обходного пути Google рекомендует переключиться на другую модель. В руководстве Claude 429 против 529 разобрана та же разница на стороне Anthropic.
403 PERMISSION_DENIED. На проект наложены ограничения, требуется верификация или ключ заблокирован. Повторные попытки не помогут.

Почему это происходит

Согласно странице документации Google о лимитах:

Три основных измерения, каждое проверяется отдельно. RPM, TPM (входные токены) и RPD контролируются независимо друг от друга. Пример из документации Google: при лимите RPM в 20 двадцать первый запрос за минуту завершится ошибкой, «даже если вы не превысили TPM или другие лимиты».
Лимиты применяются к проекту, а не к ключу. Все ключи внутри одного проекта расходуют общую квоту. Второй ключ в том же проекте не даст дополнительного запаса.
RPD сбрасывается в полночь по тихоокеанскому времени (Pacific Time). Поминутная ошибка 429 проходит в течение минуты. Дневная держится до полуночного сброса.
Лимиты зависят от модели. Для экспериментальных и preview-моделей действуют более строгие ограничения. У некоторых моделей есть дополнительные измерения, например изображения в минуту (IPM) у моделей генерации изображений или токены в день (TPD). Встроенные инструменты тоже имеют собственные квоты: для Grounding with Google Search на моделях Gemini 3 и новее по умолчанию установлен лимит 1,500 запросов в день на проект.
Лимиты по расходам. На платных уровнях также действует ограничение по сумме затрат, измеряемое на скользящем 10-минутном окне. Всплеск запросов с большим контекстом или длинным выводом может упереться в него, даже когда по RPM все в порядке.
Batch и Priority считаются отдельно. У Batch API собственные лимиты (включая количество токенов в очереди на каждую модель). У приоритетного инференса (Priority inference) тоже свои лимиты — по умолчанию 0.3x от стандартного лимита, при этом его потребление все равно учитывается в общем интерактивном трафике.

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

Бесплатный и платные уровни

Лимиты привязаны к уровню использования (usage tier) проекта, и Google повышает этот уровень автоматически по мере выполнения условий:

Уровень	Как проект его получает
Free	Активный проект или бесплатный пробный период; для некоторых проектов требуется верификация
Tier 1	Настроить и привязать активный аккаунт Cloud Billing
Tier 2 / Tier 3	Накопленный порог платежей плюс период ожидания после первого успешного списания (актуальные критерии указаны на странице лимитов)

Нюансы, на которых часто спотыкаются:

Переход с Free на Tier 1 обычно срабатывает мгновенно, а последующие повышения занимают около 10 минут. Текущий уровень можно проверить на странице Projects.
Не каждый проект или аккаунт имеет право на бесплатный уровень. Согласно руководству по устранению неполадок, создание нового ключа в том же проекте это не исправит, поскольку доступность бесплатного уровня определяется для проекта в целом. Переход на платный тариф тоже не открывает квоту бесплатного уровня.
У некоторых моделей вообще нет бесплатного уровня. Google указывает, что Gemini 4 Argon «недоступна на бесплатном уровне (Free tier)», поэтому вызывать gemini-4-argon нужно из проекта с привязанным биллингом.

Решение 1: выясните, в какой именно лимит вы уперлись

Откройте страницу Rate Limit в AI Studio и выберите модель. Сравните свое потребление по RPM, TPM и RPD с лимитами вашего уровня.
Проверьте страницу Usage на предмет всплесков — например, из-за зациклившихся повторов или пакетной задачи, работающей в том же проекте.
Посмотрите, как долго держится ошибка. Если 429 проходит примерно за минуту, причина в RPM или TPM. Если она возвращается часами, вы исчерпали RPD, который сбрасывается в полночь по тихоокеанскому времени.

Решение 2: повторяйте запросы с backoff и учитывайте `retryDelay`

Официальные SDK уже умеют повторять запросы. Например, Python SDK повторяет вызовы при 429 и 5xx до четырех раз, начиная примерно с 1 секунды и доходя максимум до 60 секунд (руководство по устранению неполадок). Если вы обращаетесь к REST API напрямую, реализуйте такую же логику: используйте экспоненциальный backoff с джиттером, повторяйте только коды 429, 408 и 5xx и ограничивайте число попыток.

python

import os, random, time, requests

URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent"
HEADERS = {"x-goog-api-key": os.environ["GEMINI_API_KEY"], "Content-Type": "application/json"}
RETRYABLE = {408, 429, 500, 503, 504}

def server_retry_delay(resp):
    """Возвращает RetryInfo.retryDelay в секундах, если он есть в теле ошибки."""
    try:
        for d in resp.json().get("error", {}).get("details", []):
            if d.get("@type", "").endswith("google.rpc.RetryInfo"):
                return float(d["retryDelay"].rstrip("s"))
    except (ValueError, KeyError):
        pass
    return None

def generate(prompt, max_retries=5):
    body = {"contents": [{"parts": [{"text": prompt}]}]}
    for attempt in range(max_retries + 1):
        resp = requests.post(URL, headers=HEADERS, json=body, timeout=300)
        if resp.ok:
            return resp.json()
        if resp.status_code not in RETRYABLE or attempt == max_retries:
            resp.raise_for_status()   # 400/402/403: исправьте запрос, не повторяйте
        backoff = min(60, 2 ** attempt) + random.uniform(0, 1)
        time.sleep(max(backoff, server_retry_delay(resp) or 0))

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

Решение 3: снизьте нагрузку по тому измерению, в которое уперлись

TPM: передавайте меньше входных данных в каждом запросе. Подрезайте историю диалога, суммаризируйте старые реплики и не отправляйте заново большие документы при каждом вызове — именно для этого существует кэширование контекста.
RPM: ставьте запросы в очередь через rate limiter, настроенный чуть ниже вашего порога, вместо того чтобы отправлять их все разом и надеяться на повторы.
RPD: перенесите фоновые задачи (оценки качества, массовую классификацию, бэкфиллы) в Batch API, у которого отдельные лимиты, не затрагивающие интерактивный трафик.
Лимиты по расходам: распределите по времени дорогие запросы с огромным контекстом или длинным ответом либо сократите длину генерируемого вывода.

Решение 4: повысьте лимит официальным способом

Если вы упираетесь в квоту при обычной рабочей нагрузке в продакшене, привяжите платежный аккаунт, чтобы вывести проект с бесплатного уровня, и дождитесь автоматического повышения тира. Если и этого недостаточно, подайте заявку на увеличение лимитов платного уровня по ссылке со страницы лимитов Google. Google отмечает, что рассматривает такие заявки, но не дает гарантий одобрения.

Если вы используете byesu

byesu — это AI API-шлюз с OpenAI-совместимым эндпоинтом: один ключ для Gemini, Claude, GPT и Grok с оплатой по мере использования (pay-as-you-go) без подписок. Два момента при работе с Gemini:

Вы можете вызывать Gemini через OpenAI-совместимый эндпоинт https://byesu.com/v1, указывая ID моделей gemini-4-argon или gemini-3.8-flash и используя тот же токен sk-, что и для остальных моделей. Уровень вашего собственного проекта в AI Studio к этим запросам не применяется.
Ошибки возвращаются в формате OpenAI. Ошибка превышения лимита или сбой апстрима от шлюза приходит в виде стандартного для OpenAI тела {"error": {"message": ..., "type": ..., "code": ...}}, а не в формате Google со status: RESOURCE_EXHAUSTED и RetryInfo. Используйте ту же логику экспоненциальной задержки, а причину смотрите в поле error.message.

Чтобы начать работу, создайте токен в консоли и следуйте руководству Быстрый старт.

Частые вопросы (FAQ)

Что означает ошибка Gemini API 429 RESOURCE_EXHAUSTED?

Ваш проект Google Cloud превысил один из лимитов частоты запросов для вызванной модели: запросов в минуту (RPM), входных токенов в минуту (TPM), запросов в день (RPD) или лимит по расходам. Превышение любого отдельного показателя вызывает ошибку, даже если по остальным еще есть запас. Подождите и повторите запрос с экспоненциальной задержкой (exponential backoff) либо снизьте частоту и размер запросов.

Повысит ли мою квоту Gemini создание еще одного API-ключа?

Нет. Лимиты Gemini API применяются на уровне проекта, а не отдельного API-ключа, поэтому все ключи внутри одного проекта делят общую квоту. Лимиты растут вместе с уровнем использования (usage tier) проекта, который зависит от привязки платежного аккаунта и истории платежей.

Когда сбрасывается дневная квота запросов (RPD) в Gemini?

Квоты запросов в день (RPD) сбрасываются в полночь по тихоокеанскому времени (Pacific Time). Поминутные лимиты восстанавливаются непрерывно, поэтому ошибка 429 из-за RPM или TPM обычно проходит в течение минуты, тогда как 429 из-за RPD сохраняется до ежедневного сброса.

Где посмотреть мои лимиты Gemini API?

Откройте страницу Rate Limit в Google AI Studio (aistudio.google.com/rate-limit). На ней показаны действующие лимиты для вашего проекта и уровня по каждой модели. На странице Projects указан текущий уровень использования каждого проекта, а на странице Usage — недавнее потребление.

Стоит ли повторять запрос сразу после ошибки Gemini 429?

Нет. Используйте экспоненциальную задержку со случайным разбросом (jitter), а если тело ошибки содержит google.rpc.RetryInfo с полем retryDelay, подождите как минимум указанное время. Ограничьте максимальное число повторов. Не повторяйте запросы при ошибках 400, 402 или 403 — они не пройдут без изменений с вашей стороны.

Gemini API 429 RESOURCE_EXHAUSTED: квоты, тарифные уровни и повторы ​

Симптомы и что означает эта ошибка ​

Почему это происходит ​

Бесплатный и платные уровни ​

Решение 1: выясните, в какой именно лимит вы уперлись ​

Решение 2: повторяйте запросы с backoff и учитывайте retryDelay ​

Решение 3: снизьте нагрузку по тому измерению, в которое уперлись ​

Решение 4: повысьте лимит официальным способом ​

Если вы используете byesu ​

Частые вопросы (FAQ) ​

Что означает ошибка Gemini API 429 RESOURCE_EXHAUSTED? ​

Повысит ли мою квоту Gemini создание еще одного API-ключа? ​

Когда сбрасывается дневная квота запросов (RPD) в Gemini? ​

Где посмотреть мои лимиты Gemini API? ​

Стоит ли повторять запрос сразу после ошибки Gemini 429? ​