Gemini API 오류 해결: 429·403 원인 확인부터 재시도 설정까지

Gemini API 호출이 실패하면 HTTP 상태 코드와 오류 메시지를 함께 확인한 뒤, 요청을 수정할지 잠시 기다릴지 결정하세요. 400은 요청 형식이나 사용 조건, 403은 접근 권한과 프로젝트 상태, 404는 모델이나 리소스를 먼저 살펴봅니다. 429는 짧은 시간에 요청이 몰린 경우와 일일 할당량이 소진된 경우를 구분해야 합니다. 500·503·504는 횟수를 제한한 재시도를 고려할 수 있지만, 계속 반복되면 요청 크기와 서비스 상태를 추가로 확인해야 합니다.

이 글은 Gemini Developer API를 직접 호출하는 개발자를 위한 안내입니다. Gemini 앱, Gemini CLI, Vertex AI의 인증 방식과 할당량을 그대로 적용하면 진단이 어긋날 수 있습니다. 아래 내용은 2026년 10월 28일 확인한 공식 문서를 기준으로 합니다.

상태 코드보다 먼저 남겨야 할 정보

오류가 난 호출의 모델 ID, API 버전, 메서드, 발생 시각과 시간대, HTTP 상태 코드, 오류 본문의 코드와 메시지를 함께 기록하세요. 같은 프로젝트의 다른 작업이 동시에 실행됐는지도 확인하면 좋습니다. 공개 로그나 지원 요청에 API 키, 인증 헤더, 개인정보가 포함된 프롬프트를 그대로 붙이지 마세요.

응답 JSON의 형식이 모든 엔드포인트에서 같지는 않습니다. generateContent에서 보던 숫자 코드나 PERMISSION_DENIED 같은 상태 이름을 Interactions API에 그대로 대입하지 마세요. 현재 공식 API 오류 문서는 Interactions API의 error.code를 rate_limit_exceeded, quota_exceeded 같은 문자열로 설명합니다. HTTP 429라는 사실은 같아도 오류 본문의 구분에 따라 다음 조치가 달라집니다.

이 표는 진단의 출발점입니다. 실제 분류는 사용한 엔드포인트와 오류 본문을 함께 보아야 합니다. 특히 501처럼 지원하지 않는 기능을 뜻하는 응답까지 모든 5xx와 묶어 자동 재시도하지 마세요. 코드별 의미는 공식 오류 설명을 확인할 수 있습니다.

429 오류: 잠시 기다리면 되는 경우와 호출을 멈춰야 하는 경우

429가 발생하면 우선 요청을 더 보내지 말고 AI Studio에서 해당 키가 속한 프로젝트와 호출한 모델의 사용량·한도를 확인하세요. 분당 요청 수(RPM), 분당 입력 토큰 수(TPM), 일일 요청 수(RPD)는 서로 다른 제한입니다. 요청 수가 적어도 입력이 크면 TPM에 도달할 수 있습니다. 한도는 API 키별이 아니라 프로젝트별로 적용되므로, 같은 프로젝트에서 키를 추가해도 할당량이 늘어나지 않습니다. 공식 사용량 제한 문서

여러 요청을 하나로 합치면 RPM은 줄일 수 있지만, TPM이나 요청 크기 문제가 커질 수 있습니다. 반대로 긴 입력을 잘게 나누면 요청 수가 늘어납니다. 먼저 병목이 어느 지표인지 확인하고 조정해야 합니다. 모든 프로젝트에 통하는 고정 대기 간격은 없습니다.

일일 요청 한도는 미국 태평양 시간 자정에 재설정됩니다. 한국 시간으로 일정을 표시하려면 America/Los_Angeles 시간대를 기준으로 변환하세요. 서머타임 때문에 연중 같은 한국 시각으로 고정할 수 없습니다. 현재 모델과 사용 티어에 적용되는 실제 한도는 AI Studio에서 확인해야 하며, 표시된 한도가 항상 해당 처리 용량을 보장하는 것은 아닙니다. 한도와 재설정 기준

일부 계정에는 최근 10분 동안의 지출을 기준으로 한 제한도 적용됩니다. 따라서 RPM과 TPM이 낮다는 이유만으로 제한에 걸리지 않았다고 판단할 수 없습니다. 이 제한은 월간 예산이나 선불 크레딧 잔액과 구분해서 확인해야 합니다. 적용 여부는 계정의 결제 이력과 상태에 따라 달라집니다. 지출 기반 속도 제한

사용량이 0인데도 429가 발생한다면

대시보드의 숫자 하나로 서버 버그라고 결론 내리지 마세요. 먼저 키의 프로젝트, 모델, 사용량 지표, 조회 시간 범위가 실패한 호출과 일치하는지 확인합니다. 그다음 오류 본문에서 일일 할당량이나 지출 제한을 가리키는지 살펴보세요. Interactions API라면 rate_limit_exceeded와 quota_exceeded의 구분도 확인합니다. 후자는 짧은 재시도 루프로 해결할 문제가 아닐 수 있습니다. 오류 코드별 설명

사용량을 Google Cloud의 서비스 계정 지표에서 보고 있다면 키 유형도 확인하세요. 공식 문서는 authorization key로 보낸 요청이 해당 지표에 기록되지 않는다고 설명합니다. 이는 모든 AI Studio 사용량 화면이 비어 있다는 뜻은 아닙니다. API 키 유형과 사용량 지표

여기까지 확인해도 설명되지 않으면 요청 시각, 모델, 상태 코드와 민감정보를 제거한 오류 메시지를 모아 지원을 요청하세요. 근거 없이 “15분만 기다리면 해결된다”고 보고 호출을 계속 보내는 것은 피해야 합니다.

403 오류: 키를 바꾸기 전에 프로젝트 상태 확인하기

403은 권한 거부를 나타내지만, 원인이 항상 API 키에 있는 것은 아닙니다. 키가 속한 프로젝트의 사용 자격과 결제 상태도 함께 확인해야 합니다. 공식 문서는 무료 티어 사용이 제한된 프로젝트, 결제가 필요한 상태, 프로젝트·결제 계정의 정책상 정지, 유출되어 차단된 키를 서로 다른 문제로 설명합니다. 프로젝트 접근 제한 해결 안내

1. 실행 환경이 의도한 키를 읽는지 확인합니다. 키 자체를 출력하지 말고, 배포 설정의 참조 대상과 키가 속한 프로젝트를 대조하세요.
2. 오류가 키 제한이나 유출·차단을 가리키면 해당 제한을 확인하고, 유출된 키는 폐기·교체합니다. 새 키는 소스 코드에 넣지 않고 비밀정보 저장소나 환경 변수로 전달합니다.
3. 프로젝트 사용 자격 또는 결제 문제라면 키 재발급을 반복하지 말고 프로젝트와 연결된 결제 계정의 상태를 확인합니다. 무료 티어 사용 자격이 없는 프로젝트에서는 유료 결제 계정 연결이 필요할 수 있으며, 이 경우 사용료가 발생합니다. 결제를 연결한다고 무료 할당량이 생기는 것은 아닙니다.
4. 실행 지역에 관한 메시지가 나오면 실제 요청이 실행되는 지역과 지원 지역 목록을 대조합니다. 한국어를 사용한다는 이유로 서버도 한국에 있다고 가정하지 마세요. 결제 설정만으로 지원하지 않는 지역의 조건이 해소된다고 볼 수도 없습니다.

키의 제한을 무조건 해제하는 것도 올바른 해결책이 아닙니다. 현재 공식 안내에서는 제한이 없는 standard key는 거부되지만, 적절한 제한이 설정된 standard key는 계속 사용할 수 있다고 설명합니다. AI Studio에서 2026년 5월 28일 이후 새로 만든 키는 서비스 계정에 연결된 authorization key입니다. 키 유형을 확인하고 의도한 Gemini API에 맞는 제한을 적용하세요. 현재 API 키 안내

models.list가 200으로 응답해도 생성 권한까지 확인된 것은 아닙니다. 공식 문서에 따르면 모델 목록 조회는 키의 존재를 확인할 수 있지만 프로젝트 사용 자격이나 결제 상태를 검사하지 않습니다. generateContent 등의 생성 호출은 별도로 실패할 수 있습니다. 필요한 설정을 바로잡은 뒤 최소한의 생성 요청으로 확인하되, 실제 호출에는 해당 요금과 할당량이 적용됩니다. 목록 조회와 생성 호출의 차이

업로드한 파일을 함께 보내는 요청에서만 403이나 리소스 관련 오류가 난다면 파일의 프로젝트, 권한, 존재 여부도 확인하세요. Files API 파일은 업로드 후 48시간이 지나면 자동 삭제됩니다. files.get으로 메타데이터를 확인하고 만료됐다면 필요한 파일을 다시 올려 새 참조를 사용하세요. 파일을 빼고 성공했다고 해서 원래의 파일 분석 작업까지 복구된 것은 아닙니다. Files API 보관 기간

400·404 오류: 요청과 모델을 한 항목씩 대조하기

400이 발생하면 메시지에 나온 필드부터 수정하세요. JSON 구조, 필수 값, 입력 형식, 선택한 모델의 지원 기능을 확인합니다. FAILED_PRECONDITION처럼 사용 조건을 가리키는 경우에는 본문을 계속 바꾸기보다 프로젝트·지역·결제 조건을 확인하는 편이 맞습니다.

최소한의 텍스트 입력으로 줄여 재현한 다음, 도구나 추가 설정을 하나씩 되돌리면 실패를 일으킨 항목을 좁힐 수 있습니다. 다만 최소 요청의 성공은 원래의 파일·도구·복잡한 입력까지 지원한다는 뜻이 아닙니다. 마지막에는 필요한 기능을 모두 복원한 요청을 다시 확인해야 합니다.

샘플 코드의 모델 이름을 오래된 다른 모델로 바꾸는 방식도 피하세요. 404가 발생하면 정확한 모델 ID와 API 버전, 요청 메서드, 파일 경로를 확인하고 현재 모델 목록과 지원 중단 안내를 대조하세요. 과거에 작동한 모델이라도 현재 프로젝트에서 접근 가능한지는 별도로 확인해야 합니다.

모델 설정 역시 세대별로 다릅니다. 예를 들어 현재 공식 안내는 Gemini 3.6 이상과 4에서 temperature, top_p, top_k를 무시하고 경고하며, 향후에는 400을 반환할 예정이라고 설명합니다. 따라서 특정 temperature 값이 모든 Gemini 모델에서 필수라고 단정할 수 없습니다. 먼저 선택한 모델의 기본 설정으로 확인하고 필요한 옵션만 추가하세요. 모델 매개변수 관련 안내

Python과 Node.js에서 재시도 횟수 제한하기

현재 공식 SDK는 Python의 google-genai와 JavaScript의 @google/genai입니다. 이전 google-generativeai와 @google/generative-ai 예제를 그대로 섞어 쓰지 마세요. 공식 라이브러리 안내

아래 예제는 500·503·504만 최초 요청을 포함해 최대 3회 시도하도록 설정합니다. SDK가 재시도를 담당하므로 바깥에 재시도 루프를 추가하지 않습니다. 429는 원인을 먼저 판단하도록 자동 재시도 목록에서 제외했습니다. 단기 속도 제한임을 확인한 경로에서만 429를 추가하고, 일일 할당량이나 크레딧 소진은 호출을 멈추는 별도 처리가 필요합니다.

timeout은 밀리초, 재시도 지연 값은 초 단위입니다. 여기서는 요청 타임아웃을 30초, 초기 지연을 1초, 최대 지연을 8초로 선택했습니다. 이는 예시 설정이며 서비스가 권장하는 보편적인 값이나 전체 작업의 완료 시간 보장이 아닙니다. 재시도에는 추가 요청 시간과 대기 시간이 필요하므로 사용자 응답 시간 예산도 별도로 정해야 합니다. 설정 의미는 Python SDK와 JavaScript 재시도 옵션에 설명되어 있습니다.

SDK가 환경 변수를 자동으로 찾도록 사용할 때는 GOOGLE_API_KEY와 GEMINI_API_KEY가 함께 설정되어 있으면 전자가 우선합니다. 아래 예제는 이런 혼동을 줄이기 위해 GEMINI_API_KEY를 읽어 명시적으로 전달합니다. 기존 앱에서는 키 값을 출력하지 말고 어느 변수나 비밀정보를 참조하는지부터 확인하세요. 환경 변수 설정 안내

Python 예제

python -m pip install google-genai로 설치하고, 실행 환경에 GEMINI_API_KEY와 GEMINI_MODEL을 설정하세요. GEMINI_MODEL에는 현재 프로젝트에서 사용할 수 있는 정확한 모델 ID를 넣습니다. 다음 코드를 gemini_check.py로 저장한 뒤 python gemini_check.py로 실행합니다.

import os
from google import genai
from google.genai import errors, types

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="연결을 확인하는 짧은 문장을 작성해 주세요.",
        )
        print(response.text or "텍스트가 없습니다. 응답의 종료 사유를 확인하세요.")
    except errors.APIError as exc:
        print(f"호출 실패: HTTP {exc.code}. 오류 본문을 안전하게 확인하세요.")
        raise SystemExit(1) from None

Node.js 예제

npm install @google/genai로 설치합니다. 같은 환경 변수 두 개를 설정한 뒤 아래 코드를 gemini-check.mjs로 저장하고 node gemini-check.mjs로 실행하세요.

import { GoogleGenAI, ApiError } from "@google/genai";

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.0,
      maxDelay: 8.0,
      expBase: 2.0,
      jitter: 1.0,
      httpStatusCodes: [500, 503, 504],
    },
  },
});

try {
  const response = await ai.models.generateContent({
    model,
    contents: "연결을 확인하는 짧은 문장을 작성해 주세요.",
  });
  console.log(response.text || "텍스트가 없습니다. 응답의 종료 사유를 확인하세요.");
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`호출 실패: HTTP ${error.status}. 오류 본문을 안전하게 확인하세요.`);
    process.exitCode = 1;
  } else {
    throw error;
  }
}

두 예제는 Python google-genai 2.33.0과 JavaScript @google/genai 2.31.0에서 가짜 키와 모의 응답으로 검사했습니다. 확인 범위는 호출 구성, 재시도 대상과 최대 시도 횟수입니다. 실제 Google API 호출, 계정 권한, 요금, 서비스 복구 여부는 검증하지 않았습니다.

성공 응답에서도 텍스트가 비어 있을 수 있으므로 HTTP 오류와 빈 출력을 구분하세요. 반대로 제한 횟수를 모두 사용했다면 실패를 호출자에게 알려야 합니다. 무한 재시도로 바꾸거나 성공한 것처럼 빈 문자열을 반환하지 마세요. SDK와 작업 큐 양쪽에서 각각 재시도하면 실제 요청 수가 예상보다 늘어날 수 있습니다. 공식 재시도 지침

500·503·504가 계속될 때 확인할 순서

먼저 Gemini 공식 상태 페이지에서 관련 서비스의 공지를 확인하세요. 공지가 있다고 모든 실패의 원인이 같아지는 것은 아니며, 공지가 없다고 개별 요청의 문제가 배제되는 것도 아닙니다.

• 500이 특정 입력에서 반복된다면 민감정보를 제거한 최소 재현 요청으로 범위를 좁혀 보세요. 입력 크기나 특정 옵션을 바꿨을 때 결과가 달라지는지 비교하면 지원 요청에 필요한 단서를 얻을 수 있습니다.
• 503이 여러 요청에서 발생한다면 새 작업의 동시 실행을 줄이고 제한된 재시도를 적용하세요. 계속 실패하면 일정 시간 요청 전송을 중단하고, 사용자에게 지연이나 실패를 알릴 경로를 마련합니다.
• 504 또는 클라이언트 타임아웃이라면 서버가 HTTP 504를 반환했는지, 클라이언트가 먼저 대기를 종료했는지 구분하세요. 클라이언트 대기 시간을 늘려도 서버 측 처리 기한을 바꿀 수는 없습니다. 입력을 줄이거나 작업을 나눌 수 있는지 함께 검토합니다.

타임아웃은 서버가 아무 작업도 하지 않았다는 증거가 아닙니다. 동일한 생성을 다시 요청하면 중복 처리와 비용이 발생할 수 있다는 점을 고려해야 합니다. 지원하지 않는 기능을 뜻하는 501이나 잘못된 요청을 같은 복구 경로에 넣지 않는 것도 중요합니다. 오류 의미와 재시도 시 유의사항을 함께 확인하세요.

지원이 필요한 경우에는 실패 시각과 시간대, 모델 ID, SDK 버전, 호출 메서드, 상태 코드, 민감정보를 제거한 메시지, 최소 재현 조건을 준비하세요. 원본 프롬프트나 키 대신 재현에 필요한 정보만 전달하면 문제를 좁히기 쉽습니다.

자주 묻는 질문

결제를 연결하면 429 오류가 없어지나요?

항상 그렇지는 않습니다. 사용 티어와 프로젝트 상태에 따라 적용되는 한도가 달라질 수 있지만, 유료 프로젝트에도 사용량 제한이 있습니다. 먼저 어느 한도에 도달했는지 확인하고 현재 프로젝트의 실제 값을 확인하세요. 특정 배수의 한도 증가나 즉시 복구를 전제로 결제하면 안 됩니다. 공식 사용량 제한

403이 나면 API 키를 새로 만들면 되나요?

유출되거나 차단된 키라면 교체가 필요할 수 있습니다. 하지만 프로젝트의 사용 자격이나 결제 계정이 원인이라면 같은 프로젝트의 키를 다시 만들어도 그 조건은 바뀌지 않습니다. 오류 메시지가 가리키는 대상부터 확인하세요. 프로젝트 접근 문제

실패한 요청도 요금이나 할당량에 포함되나요?

공식 결제 FAQ는 400 또는 500으로 실패한 요청에는 토큰 요금을 부과하지 않지만 할당량에는 반영된다고 설명합니다. 이 설명을 모든 오류, 타임아웃, 중복 생성에 확대 적용하면 안 됩니다. 실패 요청의 과금 안내

모델 목록 조회는 성공하는데 생성만 실패하는 이유는 무엇인가요?

목록 조회 성공만으로 프로젝트의 생성 사용 자격이나 결제 상태가 확인되지는 않기 때문입니다. 생성 요청의 오류 본문을 기준으로 프로젝트·결제·모델 접근 조건을 확인해야 합니다. 공식 문제 해결 안내