지니제스트 테크 블로그 배너
지니제스트Tech Archive
AI7분 소요

Gemini API 503 UNAVAILABLE 오류와 재시도 설정 정리

•
지지니제스트

Gemini API가 This model is currently experiencing high demand라며 503 UNAVAILABLE을 돌려줄 때 원인과 대응을 정리했습니다. 429와 503의 차이, 공식 문서가 권하는 지수 백오프와 지터, 실제 자동 발행 서버에서 8초와 16초 대기로는 넘기지 못했던 사례와 대기 시간을 늘린 설정을 다룹니다.

Gemini API 503 UNAVAILABLE 오류와 재시도 설정 정리

Gemini API를 호출했는데 HTTP 503과 함께 This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.가 돌아오면 요청이 틀린 것이 아니라 서버 쪽이 일시적으로 받아 주지 못한다는 뜻입니다. 키나 코드를 고치기 전에 이 오류가 어떤 종류인지부터 가르는 편이 빠릅니다.

저는 이 블로그의 자동 발행 서버에서 같은 오류를 겪었습니다. 짧게 두 번 기다렸다 다시 시도하는 설정으로는 넘기지 못했고, 그 경험을 바탕으로 대기 시간을 바꿨습니다. 이 글은 오류의 성격, 공식 문서의 권장 방식, 직접 적용한 설정을 정리한 것입니다.

Gemini API 503 오류를 오류 확인에서 재시도 설정까지 나눈 대응 순서 그림
Gemini API 503 대응 순서


503은 내 요청이 아니라 서버 상태 문제

오류 응답의 본문은 아래와 같은 모양입니다.

JSON
{
  "error": {
    "code": 503,
    "message": "This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.",
    "status": "UNAVAILABLE"
  }
}

Google AI Studio의 문제 해결 문서는 503 UNAVAILABLE을 일시적인 서비스 오류로 분류하고, 지수 백오프로 재시도하라고 안내합니다. 반대로 400처럼 요청 자체가 잘못된 클라이언트 오류는 재시도하지 말고 요청을 고치라고 합니다. 그래서 상태 코드별로 할 일이 갈립니다.

코드 상태 성격 할 일
400 요청 오류 문법 등 요청이 잘못됨 재시도하지 말고 요청을 고침
403 PERMISSION_DENIED 키 차단, 결제나 인증 필요 등 원인에 맞게 키 재발급이나 결제 확인
429 RESOURCE_EXHAUSTED 호출 한도 초과 지수 백오프로 재시도, 일일 한도면 다음 날까지 대기
503 UNAVAILABLE 일시적 서비스 오류 지수 백오프로 재시도

429와 503은 둘 다 재시도 대상처럼 보이지만 원인이 다릅니다. 429는 내 프로젝트의 한도 문제이고 503은 서비스 전체의 수요 문제라서, 내 호출량을 줄여도 503은 사라지지 않습니다. 또 같은 429라도 일일 한도(PerDay)를 다 쓴 경우에는 몇 분 기다려도 풀리지 않으므로 대기 재시도가 호출만 낭비합니다.


공식 문서가 권하는 재시도 방식

문서에 따르면 공식 SDK는 429와 5xx를 기본으로 자동 재시도하며, Python SDK는 약 1초에서 시작해 최대 60초 지연으로 최대 네 번 재시도합니다. SDK를 쓰지 않고 REST를 직접 호출하거나 별도 로직을 짠다면 아래 네 가지를 직접 챙기라고 안내합니다.

  1. 1초, 2초, 4초, 8초처럼 대기 시간을 두 배씩 늘리는 지수 백오프
  2. 여러 클라이언트가 같은 순간에 다시 몰리지 않도록 무작위 지터
  3. 일시적 오류만 재시도하고 클라이언트 오류는 재시도하지 않기
  4. 최대 재시도 횟수 제한

문서는 오류 해결책으로 모델 교체를 권하지 않습니다. 지원되는 모델과 올바른 API 버전을 쓰는지 확인하라는 정도이고, 모델이 바뀐다고 서비스 수요가 달라지지는 않습니다.


직접 겪은 사례와 원인

자동 발행 서버가 gemini-2.5-flash를 호출하다 저녁 18시대에 실패한 로그는 이렇습니다.

시각(UTC) 일어난 일
10:00:18 두 번째 생성 호출 시작
10:01:30 72초 만에 503 응답, 8초 대기 후 재시도
10:01:48 다시 503, 16초 대기 후 재시도
10:02:12 세 번째도 503, 재시도 횟수 소진으로 실패 처리

첫 호출이 실패하기까지 약 70초가 걸렸고 이후 두 번의 재시도는 합쳐서 24초만 기다렸습니다. 호출 시작부터 포기까지 2분이 채 안 걸렸으니 수요 급증이 그보다 길게 이어지면 그대로 실패합니다. 문서의 예시(1, 2, 4, 8초)를 그대로 따라 한 설정이 이런 몇 분짜리 급증에는 짧았던 것입니다.

같은 실행에는 기다림과 무관한 문제도 하나 있었습니다. 첫 번째 시도는 503이 아니라 리서치 단계의 검증된 공식 출처가 1개뿐이라는 품질 게이트에 걸려 재시도로 넘어갔고, 그 재시도가 하필 503 구간에 들어갔습니다. 503 자체는 서버 쪽 일이므로 코드로 없앨 수는 없고, 견디는 방법만 개선할 수 있었습니다.


적용한 설정

수정은 세 가지입니다.

1. 503의 대기 시간을 15초, 30초, 60초, 90초로 늘렸습니다. 재시도 횟수는 2회에서 4회로 늘렸고, 대기는 최대 90초로 상한을 두었습니다. 한 번 실패한 호출은 합쳐서 약 3분 반을 더 기다린 뒤에야 포기합니다.

JAVASCRIPT
const TRANSIENT_STATUS = new Set([408, 429, 500, 502, 503, 504]);

// 503은 수 분 지속될 수 있어 초 단위 백오프로는 넘기지 못한다
const waitMs = res.status === 503
  ? Math.min(90000, 15000 * 2 ** attempt)   // 15s → 30s → 60s → 90s
  : backoffBaseMs * 2 ** attempt;           // 그 외 일시 오류는 기존 값
await sleep(waitMs);

2. 일일 한도 429는 재시도하지 않습니다. 응답 본문에 PerDay가 있으면 대기해도 풀리지 않으므로 즉시 포기하게 이미 막아 두었습니다. 대기 시간을 늘리면서 이 구분이 더 중요해졌습니다. 이게 없으면 하루 한도가 끝난 날에 4번씩 몇 분을 기다리게 됩니다.

3. 같은 세션의 재시도 횟수를 하루 2회에서 3회로 늘렸습니다. 이 서버는 실패하면 30분 뒤 같은 세션을 다시 시도하고, 알림 메시지에도 이제 구글 서버 과부하일 때 자동 재시도가 예약된다고 표시합니다. 알림만 보고 직접 개입해야 하나 고민할 필요가 없도록 한 것입니다.


직접 호출하는 코드에 적용하기

SDK 없이 fetch로 부른다면 아래 정도로 정리할 수 있습니다. 지터를 섞어 여러 작업이 같은 시각에 재시도하지 않게 했습니다.

JAVASCRIPT
async function callWithRetry(url, body, { maxRetry = 4 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (res.ok) return res.json();

    const text = await res.text();
    const retryable = [429, 500, 503, 504].includes(res.status);
    const daily = res.status === 429 && /PerDay/i.test(text);
    if (!retryable || daily || attempt >= maxRetry) {
      throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
    }
    const base = Math.min(90000, 15000 * 2 ** attempt);
    const jitter = Math.random() * 3000;
    await new Promise((r) => setTimeout(r, base + jitter));
  }
}

호출 한 번의 타임아웃도 같이 봐야 합니다. 위 사례에서 503은 즉시 오지 않고 70초 넘게 걸려서 돌아왔습니다. 그러니 AbortSignal.timeout을 너무 짧게 잡으면 503을 받기 전에 타임아웃으로 끊겨 다른 오류로 보일 수 있습니다.


그래도 계속 실패할 때 확인할 것

대기를 늘려도 한참 계속된다면 아래 순서로 봅니다.

  • 응답 본문의 상태가 UNAVAILABLE인지, RESOURCE_EXHAUSTED인지 먼저 확인합니다. 후자면 한도 문제입니다.
  • 429라면 AI Studio의 rate limit 화면에서 내 프로젝트의 실제 한도와 사용량을 확인합니다. 한도 숫자는 공식 문서에 고정으로 적혀 있지 않고 프로젝트마다 다를 수 있습니다.
  • 사용하는 모델이 지원 중단 예정인지 모델 문서에서 확인합니다.
  • 예약 작업이라면 정해진 시각에 한 번만 호출하지 말고, 실패 시 일정 시간 뒤에 다시 시도하는 작업 단위 재시도를 별도로 두는 편이 안전합니다. 호출 단위 재시도로 넘지 못하는 장시간 급증은 이쪽이 받아 줍니다.

핵심 요약

  • 503 UNAVAILABLE은 요청이 아니라 서비스 상태 문제이며, 공식 문서는 지수 백오프 재시도를 권합니다.
  • 1초, 2초, 4초 같은 짧은 백오프는 몇 분 이어지는 급증을 넘기지 못할 수 있어서 대기를 15초에서 90초까지 늘렸습니다.
  • 일일 한도 429는 재시도해도 풀리지 않으니 구분해서 즉시 포기하게 합니다.
  • 여러 작업이 있으면 지터를 섞고, 호출 단위 재시도와 별개로 작업 단위 재시도를 둡니다.

참고 자료