문제 해결 안내(Troubleshooting guide)

이 가이드는 Gemini API를 호출할 때 발생하는 일반적인 문제를 진단하고 해결하는 데 도움을 줘요. 문제는 Gemini API 백엔드 서비스에서 오거나 클라이언트 SDK에서 발생할 수 있어요. 우리의 클라이언트 SDK는 다음 저장소에 오픈소스로 공개되어 있어요:

API 키 문제가 발생하면 API 키 설정 가이드에 따라 API 키를 올바르게 설정했는지 확인해 보세요.

출처: 원문

본문

오류 코드(Error codes)

HTTP 상태 코드, generation blocked 코드, 콘텐츠 오류 코드를 포함한 모든 오류 코드의 전체 레퍼런스는 API errors 페이지를 참고하세요.

재시도 전략(Retry strategy)

요청을 재시도하라는 오류(예: 429 RESOURCE_EXHAUSTED 또는 503 UNAVAILABLE)를 받으면 지수 백오프(exponential backoff) 전략을 구현하는 것을 권장해요. 이는 첫 재시도 전에 짧게 기다렸다가, 이후 재시도 사이의 대기 시간을 점진적으로 늘리는 방식이에요.

Gemini API의 공식 클라이언트 SDK(예: Python SDK)에는 타임아웃, 네트워크 문제, 요금 한도(429, 5xx 상태 코드) 같은 일시적 오류를 처리하는 지수 백오프 자동 재시도 로직이 기본적으로 포함되어 있어요. 예를 들어 Python SDK는 일시적 오류를 초기 약 1초, 최대 60초 지연으로 최대 4회 자동 재시도해요.

REST API 요청을 직접 만들거나 재시도 로직을 직접 커스터마이징한다면 다음 모범 사례를 따라 성공 확률을 높이고 서비스에 과부하를 주지 않도록 하세요:

지수 백오프 사용: 첫 재시도 전에 짧게 기다렸다가(예: 1초), 지연을 지수적으로 늘려요(예: 2초, 4초, 8초).
지터(jitter) 추가: 모든 클라이언트가 정확히 같은 시각에 재시도하지 않도록 지연에 무작위 "지터"를 추가해요.
특정 오류에만 재시도: 일시적 오류(429, 408, 5xx)에만 재시도해요. 잘못된 API 키, Prepay 크레딧 소진, 잘못된 문법 같은 문제를 나타내는 클라이언트 오류(400, 402, 403)에는 재시도하지 마세요.
최대 재시도 횟수 설정: 무한 루프를 방지하기 위해 최대 재시도 횟수를 정의하세요.

API 호출의 모델 파라미터 오류 확인

모델 파라미터가 다음 값 범위 내에 있는지 확인하세요:

모델 파라미터	값(범위)
Candidate count	1–8 (정수)
Temperature	0.0–1.0
Max output tokens	models 페이지에서 사용 중인 모델의 최대 토큰 수를 확인해요.
TopP	0.0–1.0

파라미터 값 확인과 함께 올바른 API 버전(예: /v1 또는 /v1beta)과 필요한 기능을 지원하는 모델을 사용하고 있는지도 확인하세요. 예를 들어 어떤 기능이 Beta 릴리스라면 그 기능은 /v1beta API 버전에서만 사용할 수 있어요.

올바른 모델을 사용하고 있는지 확인

우리의 models 페이지에 나열된 지원 모델을 사용하고 있는지 확인하세요.

thinking 모델에서 더 높은 지연 시간 또는 토큰 사용량

지연 시간이나 토큰 사용량이 높아지는 경우는 대부분 Gemini 3.x 모델이 기본적으로 thinking을 활성화하기 때문이에요. 단종된 Gemini 2.5 모델도 기본적으로 thinking을 사용해요.

Thinking 모델은 품질 향상을 위해 내부 추론 토큰을 생성해요. 이 추론 과정은 응답 지연 시간과 총 토큰 소비를 모두 증가시켜요.

지연 시간을 낮추거나 비용을 최소화하는 것이 우선이라면 thinking 수준을 낮추거나 thinking을 끌 수 있어요.

구성 방법과 코드 샘플은 thinking 가이드를 참고하세요.

안전 문제(Safety issues)

API 호출에서 안전 설정 때문에 프롬프트가 차단되었음을 알게 되면, API 호출에서 설정한 필터와 관련해 프롬프트를 검토해 보세요.

BlockedReason.OTHER가 표시되면 쿼리나 응답이 서비스 약관을 위반하거나 지원되지 않는 것일 수 있어요.

반복 생성(Recitation) 문제

RECITATION 이유로 모델 출력 생성이 중단되면, 모델 출력이 특정 데이터와 유사할 수 있음을 의미해요. 이를 해결하려면 프롬프트/컨텍스트를 가능한 한 고유하게 만들고 더 높은 temperature를 사용해 보세요.

temperature, top_p, top_k 파라미터는 모델이 응답을 생성하는 방식을 제어해요. 이 파라미터를 수정할 수는 있지만, Gemini 3.x 모델에서는 기본값으로 두는 것을 강력히 권장해요. 이 파라미터를 변경하면(예: temperature를 1.0 미만으로 설정) 특히 복잡한 수학·추론 작업에서 반복(looping)이나 성능 저하 같은 예상치 못한 동작이 발생할 수 있어요.

반복 토큰 문제(Repetitive tokens issue)

반복되는 출력 토큰이 보이면 다음 제안을 시도해 반복을 줄이거나 없앨 수 있어요.

반복 유형	원인	해결 방법
Markdown 표의 반복되는 하이픈	모델이 시각적으로 정렬된 Markdown 표를 만들려고 할 때 표 내용이 길어 발생할 수 있어요. 하지만 Markdown에서 정렬은 올바른 렌더링에 필요하지 않아요.	프롬프트에 Markdown 표 생성에 대한 구체적인 지침을 추가하고, 그 지침을 따르는 예시를 제공하세요. temperature를 조정해 볼 수도 있어요. 코드나 Markdown 표 같은 매우 구조화된 출력을 생성할 때는 높은 temperature(>= 0.8)가 더 잘 동작하는 것으로 나타났어요. 다음은 이 문제를 방지하기 위해 프롬프트에 추가할 수 있는 지침 예시예요: "Markdown 표 형식: 구분선은 헤더 행 아래에 포함해야 하며 열당 하이픈 3개만 사용(예: \|---\|---\|---\|). `----`, `-----`, `------`처럼 더 많은 하이픈을 사용하면 오류가 발생할 수 있어요. 구분 문자열에는 항상 \|:---\|, \|---:\|, 또는 \|---\|를 사용하세요. 열을 정렬하지 말고 항상 \|---\|를 사용하세요. 셀 내용은 간결하게 유지하세요. 열 머리글이나 셀을 다른 내용 너비에 맞추려고 공백을 많이 채우지 마세요. 각 측면에 공백 하나만 있으면 충분해요."
Markdown 표의 반복 토큰	반복되는 하이픈과 비슷하게, 모델이 표 내용을 시각적으로 정렬하려 할 때 발생해요. Markdown에서 정렬은 올바른 렌더링에 필요하지 않아요.	시스템 프롬프트에 "표 머리글에 머리글 바로 뒤에 ' \|'를 즉시 추가하라" 같은 지침을 추가해 보세요. temperature를 조정해 보세요. 더 높은 temperature(>= 0.8)는 일반적으로 출력의 반복이나 중복을 없애는 데 도움이 돼요.
구조화된 출력의 반복되는 줄바꿈(`\n`)	입력에 `\u`나 `\t` 같은 유니코드 또는 이스케이프 시퀀스가 포함되면 반복되는 줄바꿈이 발생할 수 있어요.	프롬프트에서 금지된 이스케이프 시퀀스를 UTF-8 문자로 찾아 교체하세요. 예를 들어 JSON 예시의 `\u` 이스케이프 시퀀스는 모델이 출력에서도 이를 사용하게 만들 수 있어요. 허용되는 이스케이프에 대해 모델에 지시하세요. "따옴표 문자열에서 허용되는 이스케이프 시퀀스는 \\, \n, \"뿐이에요. \u 이스케이프 대신 UTF-8을 사용하세요" 같은 시스템 지침을 추가하세요.
구조화된 출력의 반복 텍스트	모델 출력의 필드 순서가 정의된 구조화 스키마와 다를 때 반복 텍스트가 발생할 수 있어요.	프롬프트에서 필드 순서를 지정하지 마세요. 모든 출력 필드를 필수로 만들세요.
반복적인 도구 호출	모델이 이전 생각의 맥락을 잃거나 호출해야 하는 엔드포인트를 사용할 수 없을 때 발생할 수 있어요.	모델이 생각 과정 내에서 상태를 유지하도록 지시하세요. 시스템 지시문 끝에 "조용히 생각할 때: 항상 생각을 작업의 현재 진행 상황에 대한 간략한(한 문장) 요약으로 시작하세요. 특히 작업이 이미 끝났는지 고려하세요"를 추가하세요.
구조화 출력에 속하지 않는 반복 텍스트	모델이 해결할 수 없는 요청에서 멈출 때 발생할 수 있어요.	thinking이 켜져 있으면 지침에서 문제를 어떻게 생각할지에 대한 명시적인 지시를 피하고 최종 출력만 요청하세요. 더 높은 temperature(>= 0.8)를 시도해 보세요. "간결하게 하세요", "반복하지 마세요", "답을 한 번만 제공하세요" 같은 지침을 추가하세요.

차단되었거나 작동하지 않는 API 키

이 섹션에서는 Gemini API 키가 차단되었는지 확인하는 방법과 대처 방법을 설명해요.

키가 차단되는 이유 이해하기

일부 API 키가 공개적으로 노출되었을 수 있는 보안 취약점을 발견했어요. 데이터를 보호하고 무단 액세스를 방지하기 위해, 알려진 유출 키가 Gemini API에 접근하지 못하도록 선제적으로 차단했어요.

키가 영향을 받는지 확인하기

키가 유출된 것으로 알려졌다면 더 이상 그 키를 Gemini API에 사용할 수 없어요. Google AI Studio에서 API 키 중 Gemini API 호출이 차단된 게 있는지 확인하고 새 키를 생성할 수 있어요. 이 키를 사용하려 할 때 다음과 같은 오류가 반환될 수도 있어요:

Your API key was reported as leaked. Please use another API key.

차단된 API 키에 대한 조치

Google AI Studio를 사용해 Gemini API 통합을 위한 새 API 키를 생성해야 해요. 새 키가 안전하게 유지되고 공개적으로 노출되지 않도록 API 키 관리 방식을 검토하는 것을 강력히 권장해요.

취약점으로 인한 예상치 못한 요금

청구 지원 케이스를 제출하세요. 청구 팀이 이 문제를 처리 중이며 가능한 한 빨리 업데이트를 안내할 거예요.

유출 키에 대한 Google의 보안 조치

내 API 키가 유출되면 Google은 비용 초과와 남용으로부터 제 계정을 어떻게 보호해 주나요?

Google AI Studio에서 새 키를 요청할 때 기본적으로 Google AI Studio에만 제한되고 다른 서비스에서는 받아들이지 않는 API 키를 발급하는 방향으로 전환하고 있어요. 이는 의도하지 않은 교차 키 사용을 막는 데 도움이 돼요.
Gemini API에서 사용되는 유출 키를 기본적으로 차단해서 비용 남용과 애플리케이션 데이터 악용을 방지하고 있어요.
Google AI Studio 내에서 API 키 상태를 확인할 수 있으며, API 키 유출이 감지되면 즉각적인 조치를 위해 선제적으로 안내할 거예요.

모델 출력 개선

더 높은 품질의 모델 출력을 원한다면 더 구조화된 프롬프트를 작성해 보세요. 프롬프트 엔지니어링 가이드 페이지에서 기본 개념, 전략, 모범 사례를 소개하고 있어요.

토큰 한도 이해하기

토큰 계산 방법과 한도를 더 잘 이해하려면 Token 가이드를 읽어 보세요.

알려진 문제(Known issues)

API는 선택된 몇몇 언어만 지원해요. 지원되지 않는 언어로 프롬프트를 제출하면 예상치 못한 응답이나 차단된 응답이 발생할 수 있어요. 업데이트는 사용 가능한 언어를 참고하세요.

버그 신고

질문이 있으면 Google AI 개발자 포럼에서 토론에 참여하세요.

문제 해결 안내(Troubleshooting guide)