Gemini API 429 RESOURCE_EXHAUSTED: 올바른 제한부터 읽고 고치기

Gemini API 429 RESOURCE_EXHAUSTED 는 요청이 어떤 제한 경계를 넘었다는 뜻입니다. 바로 retry 를 늘리지 말고 AI Studio live limit, project quota pool, billing/prepay state, burst pattern, Vertex AI capacity contract 중 누가 owner 인지 먼저 분리해야 합니다.

Google troubleshooting 표는 HTTP 429 를 RESOURCE_EXHAUSTED 로 매핑하며, 호출이 rate limit 를 넘었다는 뜻입니다. rate-limits 문서는 제한이 RPM, input TPM, RPD 로 측정되고 per project, not per API key 로 적용되며, specified limits 는 보장값이 아니므로 active limits 는 AI Studio 에서 확인해야 한다고 설명합니다.

최신성: Gemini API rate limits, troubleshooting, billing, pricing, Vertex AI 429 문서는 2026년 5월 3일 다시 확인했습니다.

429 를 일반 장애가 아니라 limit branch 로 읽기

body 가 RESOURCE_EXHAUSTED 라면 limit branch 에 머무르세요. 503 UNAVAILABLE 은 temporary capacity 에 가깝고, 400 FAILED_PRECONDITION 은 region 과 billing 일 수 있습니다. 429 는 request format 은 통과했지만 현재 capacity boundary 가 거절한 상태입니다.

흔한 실수는 429 를 모두 code bug 로 보는 것입니다. Backoff 는 burst traffic 에 유용하지만 daily quota 를 만들거나 prepay balance 를 복구하거나 paid-only route 를 free route 로 바꾸지 못합니다.

전체 error body 를 로그에 남기세요. JavaScript SDK @google/genai 의 API error 에서 name, message, status 를 읽을 수 있으므로 retry classification 과 same-path escalation evidence 로 충분합니다.

quota 표보다 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 으로 갑니다. 일치하지 않으면 새 API keys 를 만들기 전에 request time, model, project, response body, usage view 를 수집합니다.

project quota, billing, route eligibility 분리

Project quota 는 pool 입니다. production, staging, local scripts, batch workers 가 같은 Google Cloud project 의 key 를 쓰면 경쟁합니다. Billing 은 account state 입니다. prepay credits 가 $0 이면 연결된 projects 의 keys 가 멈출 수 있습니다. Route eligibility 는 model contract 이므로 paid-only route 는 free-tier tuning 으로 안정화되지 않습니다.

이 분리는 billing 문제를 retry 문제로 착각하거나, route eligibility 문제를 free-tier tuning 으로 착각하는 일을 막습니다. owner 를 먼저 확정한 뒤 fix 를 선택하세요.

owner 를 안 뒤에만 retry

Retry 는 bounded 여야 합니다. exponential backoff with jitter, queue, concurrency cap, idempotency 가 필요합니다. 모든 worker 가 동시에 retry 하면 retry layer 가 spike 가 됩니다. Batch jobs 는 checkpoints, interactive apps 는 wait state 와 prompt caching 이 필요합니다.

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 contract 는 다름

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 를 봅니다. pay-as-you-go 는 global endpoint, truncated exponential backoff, QIR, traffic smoothing, reserved throughput 이 선택지입니다.

같은 HTTP code 라고 같은 system 은 아닙니다. Developer API 의 첫 증거는 보통 AI Studio 에 있고, Vertex AI 의 첫 증거는 Google Cloud project, endpoint, quota framework, provisioning contract 에 있습니다.

capacity 를 늘려야 하는 시점

route, project, billing, traffic shape 가 확인되면 capacity 결정을 합니다. 더 가벼운 model, Batch API, quota increase, Vertex AI, Provisioned Throughput, multi-provider gateway 를 선택할 수 있습니다. provider-level risk 가 되었을 때만 laozhang.ai 같은 unified routing/fallback layer 가 적합합니다.

자주 묻는 질문

Gemini API key 마다 독립된 429 limit 가 있나요?

아닙니다. Gemini API limits 는 per project, not per API key 입니다. 같은 project 의 여러 key 는 quota pool 을 공유합니다.

billing 을 켜면 RESOURCE_EXHAUSTED 가 항상 해결되나요?

항상은 아닙니다. Billing 은 tier 와 eligibility 를 바꾸지만 shared project, depleted prepay balance, daily exhaustion, burst pattern 은 별도입니다.

429 는 항상 retry 해야 하나요?

아닙니다. Retry 는 temporary pressure 와 bursts 에 적합합니다. daily quota, billing state, paid-only route 는 retry 로 고쳐지지 않습니다.

현재 Gemini API limit 는 어디에서 확인하나요?

같은 project 와 model 의 active rate-limit view 를 AI Studio 에서 봅니다. 공개 문서는 메커니즘과 tier ladder 를 설명하지만 specified limits 를 guaranteed serving capacity 로 읽으면 안 됩니다.

실무 규칙

same error body, same project, same model, same endpoint, same time window 를 맞춘 뒤 billing action, project isolation, traffic smoothing, model change, quota increase, Vertex capacity, gateway fallback 중 가장 좁은 fix 를 고르세요.