Gemini API 주요 오류 진단: 401, 404, 429, 지역 제한 (2026)

Gemini API의 오류는 이름이 많아 보이지만 실제로 진단해 보면 대부분 네 가지로 귀결됩니다. 신원이 맞지 않음, 주소가 맞지 않음, 할당량이 부족함, 네트워크가 도달하지 못함입니다. 모델 자체가 원인인 문제는 오히려 적습니다.

이 글은 오류 코드별로 나누어 최소 요청에서 시작하는 진단 순서를 제시합니다. 문제가 생기면 먼저 전체 오류 JSON을 저장한 뒤 순서대로 확인하고, Key, 주소, 모델을 동시에 바꾸지 마십시오.

안내: Google, Gemini는 해당 권리자의 상표입니다. 이 글은 2026년 10월의 일반적인 인터페이스 형태를 예로 들며 인터페이스 버전, 할당량, 지역 정책은 공식 문서와 사이트 내 모델 가격을 기준으로 합니다.

1. 먼저 오류 본문을 읽는 법

Google API 오류는 보통 JSON으로 반환되며 핵심 필드는 세 개입니다.

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code는 HTTP 상태 코드, status는 기계가 읽는 오류 유형, message에는 구체적인 원인이 담기는 경우가 많고 details에는 할당량 ID와 재시도 권장 시간이 있을 수 있습니다. 진단할 때는 세 가지를 모두 봐야 하며 "429"만 보면 "분당 제한인지 일일 할당량 소진인지"를 놓칩니다.

상태 코드	일반적인 status	대략적인 방향
401	UNAUTHENTICATED	Key 누락, 무효 또는 위치 오류
403	PERMISSION_DENIED	프로젝트 미활성, 권한 또는 지역 제한
404	NOT_FOUND	모델명, 인터페이스 경로 또는 버전 오류
429	RESOURCE_EXHAUSTED	속도, 동시성 또는 할당량 초과
400	INVALID_ARGUMENT / FAILED_PRECONDITION	파라미터 오류, 지역 미지원, 사전 조건 불충족
500/503	INTERNAL / UNAVAILABLE	업스트림 일시 장애, 보통 백오프 재시도 가능

2. 401: Key가 무효이거나 인증 방식이 잘못됨

401의 핵심은 "서버가 당신의 신원을 인정하지 않는다"입니다. 흔한 원인은 다음과 같습니다.

요청에 Key가 아예 없거나 환경 변수가 비어 있습니다.
네이티브 인터페이스에서 x-goog-api-key 대신 Authorization을 썼습니다.
OpenAI 호환 인터페이스에서 Authorization: Bearer 대신 x-goog-api-key를 썼습니다.
Key 앞뒤에 공백이나 줄바꿈이 있거나 복사할 때 따옴표가 들어갔습니다.
Key가 삭제, 교체되었거나 소속 프로젝트가 비활성화되었습니다.
게이트웨이 Key를 Google 공식 주소로 보냈거나 반대로 보냈습니다.
Key에 API 제한이 설정되어 Gemini API 호출이 허용되지 않습니다.

먼저 최소 요청 하나로 확인하십시오.

export GEMINI_API_KEY="여기에_키"

# Gemini 네이티브 인터페이스
curl "https://generativelanguage.googleapis.com/v1beta/models/<모델ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"OK라고만 답하세요"}]}]}'

# OpenAI 호환 인터페이스
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<모델ID>","messages":[{"role":"user","content":"OK라고만 답하세요"}]}'

두 명령은 서로 다른 인증 체계에 대응합니다. 어느 쪽이 통과하는지 보면 Key와 주소가 어느 체계에 속하는지 알 수 있습니다. 섞어 쓸 때 401이 나오면 Key가 고장 난 것이 아니라 조합이 틀린 것입니다.

3. 404: 모델명, 경로 또는 버전 오류

404가 반드시 "모델이 존재하지 않는다"는 뜻은 아닙니다. 흔한 경우는 다음과 같습니다.

모델 ID의 철자가 틀렸거나 API 식별자 대신 콘솔 표시 이름을 썼습니다.
모델이 현재 API 버전에 속하지 않습니다. 예를 들어 새 버전에서만 개방된 모델을 구버전 경로로 보냈습니다.
Base URL에 /v1이나 /v1beta를 더 쓰거나 빼먹어 경로 연결 후 존재하지 않는 주소가 되었습니다.
주소 끝에 슬래시가 남아 있고 클라이언트가 경로를 한 번 더 붙였습니다.
게이트웨이를 통해 호출할 때 해당 모델이 현재 그룹이나 요금제에 개통되지 않았습니다.
채팅 인터페이스로 이미지 생성이나 다른 전용 인터페이스를 호출했습니다.

진단할 때 먼저 현재 Key로 사용 가능한 모델을 나열하십시오.

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

목록에 대상 모델이 있으면 요청 경로를 확인하고, 없으면 모델 개통이나 권한 문제를 먼저 해결하십시오. 게이트웨이를 통해 호출할 때는 게이트웨이 문서가 제시한 모델 ID와 Base URL을 기준으로 하고 공식 모델명을 그대로 대입하지 마십시오.

4. 429: 속도 제한인지 할당량 소진인지 먼저 구분하기

429는 가장 오해하기 쉬운 유형입니다. 최소한 세 가지 상황을 포함합니다.

유형	전형적인 특징	처리 방향
분당 속도 제한	짧은 시간에 동시성이 높고 오류가 몇 초 안에 집중	동시성 축소, 백오프 재시도
일일 할당량 소진	당일 호출량이 상한에 도달해 지속 실패	재설정 대기, 할당량 상향 또는 방안 변경
프로젝트 단위 할당량	여러 서비스가 같은 프로젝트를 공유해 서로 잠식	프로젝트 분리, Key 분리, 별도 할당량

오류 본문의 details는 보통 할당량 ID와 재시도 권장 시간을 제공합니다. 429를 보자마자 바로 다시 보내지 마십시오. 재시도 폭풍이 상황을 더 악화시킵니다. 먼저 의존성을 설치하십시오: pip install requests. 사용 가능한 백오프 로직은 다음과 같습니다.

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<모델ID>:generateContent"
    headers = {
        "x-goog-api-key": "여기에_키",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("재시도 횟수를 모두 사용했습니다")

재시도는 일시적 혼잡만 해결하며 할당량 소진은 해결하지 못합니다. 운영 환경에는 타임아웃, 서킷 브레이커, 대체 모델도 추가해야 합니다. 그렇지 않으면 429 하나가 전체 경로를 무너뜨립니다.

5. 지역 제한: 중국 내 직접 연결이 실패하는 이유

Gemini API는 일부 국가와 지역에서만 서비스를 제공합니다. 요청 출구가 지원되지 않는 지역에 있으면 흔히 세 가지 증상이 나타납니다.

연결 타임아웃 또는 TLS 핸드셰이크 실패, 대개 네트워크 경로가 통하지 않음.
400 FAILED_PRECONDITION 반환, 문구에 location is not supported 같은 안내 포함.
403 PERMISSION_DENIED 반환, 프로젝트, 청구 또는 지역 권한과 관련될 수 있음.

여기서 혼동하기 쉬운 개념이 두 가지 있습니다. 계정 등록 지역과 요청 출구 지역입니다. 계정 자체는 사용 가능해도 서버가 지원되지 않는 지역에 배포되어 있으면 요청이 거부될 수 있습니다. 반대로 로컬 프록시로 웹 페이지를 열 수 있다고 해서 API 요청이 같은 경로로 나가는 것은 아닙니다.

처리 순서는 다음과 같습니다.

요청이 로컬, 컨테이너, 서버 중 어디에서 나가는지 확인하고 실제 출구 IP를 찾습니다.
출구 지역이 공식 지원 목록에 있는지 확인합니다.
클라우드 서버의 리전 선택을 점검하고 필요하면 지원 지역으로 옮깁니다.
업무가 주로 중국 내에 있다면 컴플라이언스 게이트웨이를 통한 접속을 평가해 네트워크와 청구를 통합 처리합니다.
"IP 교체"를 유일한 해법으로 삼지 말고 서비스 약관과 현지 법규 요건을 먼저 확인합니다.

6. 기타 빈발 오류

현상	흔한 원인	처리
400 INVALID_ARGUMENT	JSON 구조 오류, 역할 순서 오류, 이미지 형식 미지원	최소 요청에서 필드를 하나씩 추가
400 FAILED_PRECONDITION	지역 미지원, 청구 미개통, 사전 조건 누락	지역, 청구, 프로젝트 상태 확인
403 PERMISSION_DENIED	API 미활성, Key 제한, 프로젝트 권한 부족	콘솔에서 활성화하고 권한 확인
500 INTERNAL	업스트림 내부 오류	백오프 재시도, 요청 ID 기록
503 UNAVAILABLE	업스트림 과부하 또는 유지보수	백오프 재시도, 대체 모델 전환
응답은 있으나 내용 없음	안전 정책 차단, 출력 잘림	blockReason과 finishReason 확인
출력이 중간에 멈춤	최대 출력 Token 도달	상한 상향 또는 입력 축소

"응답은 있는데 내용이 없는" 경우는 자주 장애로 오해되지만 실제로는 안전 필터나 길이 제한입니다. 반환된 promptFeedback.blockReason, finishReason, usageMetadata를 먼저 보고 프롬프트를 바꿀지 파라미터를 조정할지 결정하십시오.

7. 권장 진단 순서

전체 오류 JSON, 요청 시간, 모델 ID, 요청 ID를 저장합니다.
curl로 최소 요청을 보내 클라이언트와 SDK의 간섭을 배제합니다.
Base URL, 인증 헤더, 모델 ID 세 가지를 확인합니다.
이미 사용 가능한 것으로 확인된 모델로 바꿔 모델 문제인지 경로 문제인지 판단합니다.
할당량, 청구, 프로젝트 상태를 확인해 429와 403을 구분합니다.
요청 출구 지역과 네트워크 경로를 확인합니다.
마지막으로 클라이언트 설정, 프록시 설정, 코드의 재시도 로직을 점검합니다.

한 번에 변수 하나만 바꾸십시오. 그렇지 않으면 복구되더라도 어느 단계에서 고쳐졌는지 알 수 없고 다음에 같은 문제를 반복합니다.

8. 자주 묻는 질문

401과 403의 차이는 무엇인가요?

401은 "신원이 통과하지 못함"이므로 Key, 인증 헤더, 주소가 서로 맞는지 우선 확인합니다. 403은 "신원은 통과했지만 권한이 없음"이므로 API 활성화 여부, 프로젝트 권한, Key 제한, 지역 정책을 우선 확인합니다.

429는 몇 분 기다렸다가 다시 시도하면 되나요?

할당량 유형에 따라 다릅니다. 분당 속도 제한은 백오프 후 대개 회복됩니다. 일일 할당량 소진은 재설정을 기다리거나 할당량을 올려야 합니다. 오류 본문의 할당량 ID와 재시도 권장 사항을 먼저 읽고 무작정 다시 보내지 마십시오.

지역 제한은 IP만 바꾸면 해결되나요?

반드시 그렇지는 않습니다. 실제 출구 지역, 계정 상태, 서비스 약관을 봐야 합니다. 기업 환경에서는 지원 지역에 배포하거나 컴플라이언스 게이트웨이로 통합 접속하는 편이 더 안전합니다.

공식 주소는 통하는데 게이트웨이로 바꾸면 404가 나오면 누구 문제인가요?

게이트웨이의 Base URL과 모델 ID를 먼저 확인하십시오. 게이트웨이의 모델 명명, 경로, 사용 가능 범위가 공식과 다를 수 있으므로 공식 요청을 그대로 쓰면 안 됩니다. 게이트웨이 문서의 최소 예시로 항목별로 교체하십시오.

재시도로 비용이 커지는 것을 어떻게 막나요?

최대 재시도 횟수, 지수 백오프, 타임아웃을 설정하고 429는 따로 처리하며 비멱등 요청에는 중복 제거를 추가합니다. 게이트웨이 측에는 예산 상한과 경고를 설정하십시오.

다음 단계

Gemini 오류 진단의 핵심은 먼저 "인증, 경로, 할당량, 네트워크" 네 가지를 구분하고 최소 요청으로 항목별 검증하는 것입니다. 통합 진입점이 필요하고 중국 내 직접 연결의 불확실성을 줄이고 싶다면 ZSQH AI Gateway에 등록할 수 있습니다. 모델, 할당량, 가격은 모델 가격 페이지를 기준으로 합니다.