Gemini API 429 RESOURCE_EXHAUSTED: исправьте лимит, сначала прочитав правильный слой

Gemini API 429 RESOURCE_EXHAUSTED означает, что запрос пересек конкретную границу лимита. Не начинайте с бесконечного retry. Сначала определите владельца ограничения: live limit в AI Studio, общий project quota pool, billing/prepay state, burst pattern или контракт Vertex AI.

Официальная таблица troubleshooting у Google связывает HTTP 429 с RESOURCE_EXHAUSTED: вызов превысил rate limit. Страница rate limits добавляет, что ограничения считаются по RPM, input TPM и RPD, применяются per project, not per API key, а active limits надо проверять в AI Studio, потому что specified limits не гарантируют фактическую емкость.

Свежесть: официальные страницы Gemini API rate limits, troubleshooting, billing, pricing и Vertex AI 429 были сверены 3 мая 2026 года.

Читайте 429 как ветку лимита, а не общую аварию

Если body содержит RESOURCE_EXHAUSTED, оставайтесь в ветке limit. 503 UNAVAILABLE больше похож на временную capacity проблему. 400 FAILED_PRECONDITION может означать регион free tier и billing. 429 говорит, что формат запроса принят, но текущая граница capacity отказала в обслуживании.

Главная ошибка - лечить каждый 429 как баг кода. Backoff помогает при burst трафике, но не создает daily quota, не пополняет prepay balance и не превращает paid-only route в free route.

Сохраняйте полное тело ошибки в логах. Для JavaScript SDK @google/genai API error дает поля name, message и status; этого достаточно для retry classification и для same-path evidence при эскалации.

Сначала AI Studio, затем таблицы

Google указывает, что rate limits измеряются RPM, input TPM и RPD, применяются per project, not per API key, и active limits надо смотреть в AI Studio. Поэтому публичная таблица объясняет tier ladder, но не заменяет live dashboard.

Ответьте на три вопроса: какая metric уперлась в limit; какой model, route и project вызвали ошибку; совпадает ли dashboard с ошибкой. Если dashboard насыщен, следующий шаг - capacity или traffic shaping. Если нет, соберите request time, model, project, response body и usage view, а не создавайте новые API keys.

Разделите project quota, billing и route eligibility

Project quota - это pool. Production, staging, local scripts и batch workers могут конкурировать, если используют keys одного Google Cloud project. Billing - это состояние account: paid tier может зависеть от prepay credits, а баланс $0 останавливает keys связанных проектов. Route eligibility - это контракт модели: paid-only route нельзя стабилизировать free-tier настройками.

Такое разделение предотвращает две ошибки: лечить billing как retry problem и лечить route eligibility как free-tier tuning. Сначала определите owner, затем выбирайте fix.

Retry полезен только после классификации

Retry должен быть bounded: exponential backoff with jitter, queue, concurrency cap и idempotency. Если все workers повторяют одновременно, retry layer сам становится spike. Для batch jobs нужны checkpoints; для interactive apps нужен короткий wait state и caching повторных prompts.

javascript
const retryable = new Set([429, 500, 503, 504]);

async function callWithBackoff(run, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    try {
      return await run();
    } catch (error) {
      const status = Number(error?.status || error?.code || 0);
      if (!retryable.has(status) || attempt === maxRetries) throw error;
      const delayMs = Math.min(1000 * 2 ** attempt + Math.random() * 500, 30000);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }
}

Developer API и Vertex AI имеют разные 429 контракты

Для Gemini Developer API начните с AI Studio: API key, project, usage tier, active limits, billing plan, prepay credits. Для Vertex AI начните с Google Cloud project, endpoint, region или global endpoint, quota framework и Provisioned Throughput. Vertex pay-as-you-go может требовать global endpoint, truncated exponential backoff, QIR, traffic smoothing или reserved throughput.

Один HTTP code не означает одну систему. У Developer API первое доказательство обычно в AI Studio; у Vertex AI - в Google Cloud project, endpoint, quota framework и provisioning contract.

Когда нужна большая capacity

Capacity нужна, когда route, project, billing и traffic shape уже доказаны. Можно выбрать более легкую model, Batch API, quota increase, Vertex AI, Provisioned Throughput или multi-provider gateway. laozhang.ai уместен как unified routing/fallback layer, если проблема уже стала provider-level risk.

Операторская проверка должна заканчиваться конкретным решением, а не новым списком догадок. Если исчерпан RPM, снижайте concurrency и распределяйте запросы по времени. Если исчерпан TPM, уменьшайте context, делите документы и кешируйте повторяющиеся prompts. Если исчерпан RPD, временный retry не поможет до сброса окна или до увеличения quota. Если usage view не совпадает с ошибкой, соберите request-id, timestamp, model, project, endpoint и dashboard snapshot; без этих полей support или team lead не сможет подтвердить same-path failure. Для production runbook отдельно запишите owner действия, ожидаемое время восстановления, stop rule для retries и rollback route. Тогда on-call инженер видит, когда ждать reset окна, когда просить quota increase, когда переключать модель, а когда открывать Vertex или gateway fallback. Это также помогает отличить пользовательский всплеск от соседнего batch job и от неверно выбранного paid route.

Часто задаваемые вопросы

Получает ли каждый Gemini API key собственный лимит 429?

Нет. Gemini API limits применяются per project, not per API key. Несколько keys в одном project делят quota pool.

Всегда ли billing исправляет RESOURCE_EXHAUSTED?

Нет. Billing меняет tier и eligibility, но не исправляет shared project, depleted prepay balance, daily exhaustion или burst pattern.

Нужно ли всегда повторять 429?

Нет. Retry подходит temporary pressure и bursts. Daily quota, billing state и paid-only route retry не лечит.

Где смотреть текущий лимит Gemini API?

Текущий ответ дает active rate-limit view в AI Studio для того же project и model. Публичные документы объясняют механизм и tier ladder, но specified limits не должны читаться как guaranteed serving capacity.

Практическое правило

Сначала same error body, same project, same model, same endpoint, same time window. Потом выбирайте самый узкий fix: billing action, project isolation, traffic smoothing, model change, quota increase, Vertex capacity или gateway fallback.