문제 해결 가이드

이 가이드를 사용하여 Gemini API를 호출할 때 발생하는 일반적인 문제를 진단하고 해결하세요. Gemini API 백엔드 서비스 또는 클라이언트 SDK에서 문제가 발생할 수 있습니다. 클라이언트 SDK는 다음 저장소에서 오픈소스로 제공됩니다.

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

오류 코드

HTTP 상태 코드, 생성 차단 코드, 콘텐츠 오류 코드를 포함한 모든 오류 코드의 전체 참조는 API 오류 페이지를 참고하세요.

재시도 전략

요청을 다시 시도해야 한다는 오류 (예: 429 RESOURCE_EXHAUSTED 또는 503 UNAVAILABLE)가 표시되면 지수 백오프 전략을 구현하는 것이 좋습니다. 즉, 첫 번째 재시도 전에 잠시 기다린 후 후속 재시도 사이의 대기 시간을 점차 늘립니다.

Python SDK와 같은 Gemini API의 공식 클라이언트 SDK에는 기본적으로 지수 백오프를 사용하는 자동 재시도 로직이 포함되어 있어 제한 시간, 네트워크 문제, 비율 제한 (429 및 5xx 상태 코드)과 같은 일시적인 오류를 처리합니다. 예를 들어 Python SDK는 일시적인 오류를 최대 4회까지 자동으로 재시도하며, 초기 지연 시간은 약 1초이고 최대 지연 시간은 60초입니다.

직접 REST API 요청을 하거나 재시도 로직을 맞춤설정하는 경우 다음 권장사항을 따라 요청이 성공할 가능성을 높이고 서비스에 과부하가 걸리지 않도록 하세요.

  • 지수 백오프 사용: 첫 번째 재시도 전에 잠시 기다린 후 (예: 1초) 지연 시간을 기하급수적으로 늘립니다 (예: 2초, 4초, 8초).
  • 지터 추가: 지연 시간에 무작위 '지터'를 추가하여 모든 클라이언트가 동시에 재시도하지 않도록 합니다.
  • 특정 오류 재시도: 일시적인 오류 (예: 429, 408, 5xx)만 재시도합니다. 클라이언트 오류 (예: 400, 402, 403)는 잘못된 API 키, 선불 크레딧 소진, 잘못된 문법과 같은 문제를 나타내므로 재시도하지 않습니다.
  • 최대 재시도 횟수 설정: 무한 루프를 방지하기 위해 최대 재시도 횟수를 정의합니다.

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

모델 파라미터가 다음 값 내에 있는지 확인합니다.

모델 파라미터 값 (범위)
후보 수 1~8 (정수)
온도 0.0~1.0
최대 출력 토큰 모델 페이지를 사용하여 사용 중인 모델의 최대 토큰 수를 확인합니다.
TopP 0.0~1.0

파라미터 값을 확인하는 것 외에도 필요한 기능을 지원하는 올바른 API 버전 (예: /v1 또는 /v1beta)과 모델을 사용하고 있는지 확인하세요. 예를 들어 기능이 베타 출시 버전인 경우 /v1beta API 버전에서만 사용할 수 있습니다.

올바른 모델인지 확인하기

모델 페이지에 나열된 지원되는 모델을 사용하고 있는지 확인합니다.

사고 모델 사용 시 지연 시간 또는 토큰 사용량 증가

Gemini 3.x 모델은 기본적으로 사고 기능이 사용 설정되어 있으므로 지연 시간이나 토큰 사용량이 더 높은 경우가 많습니다. 지원 중단된 Gemini 2.5 모델도 기본 사고 모드를 사용합니다.

사고 모델은 품질을 개선하기 위해 내부 추론 토큰을 생성합니다. 이 추론 프로세스는 응답 지연 시간과 총 토큰 소비를 모두 증가시킵니다.

지연 시간을 줄이거나 비용을 최소화해야 하는 경우 사고 수준을 낮추거나 사고 기능을 사용 중지할 수 있습니다.

구성 세부정보와 코드 샘플은 사고 가이드를 참고하세요.

안전 문제

API 호출의 안전 설정으로 인해 프롬프트가 차단된 경우 API 호출에서 설정한 필터와 관련하여 프롬프트를 검토합니다.

BlockedReason.OTHER가 표시되면 질문 또는 대답이 서비스 약관을 위반하거나 지원되지 않을 수 있습니다.

인용 문제

RECITATION 이유로 인해 모델이 출력 생성을 중지하는 경우 모델 출력이 특정 데이터와 유사할 수 있음을 의미합니다. 이 문제를 해결하려면 프롬프트 / 컨텍스트를 최대한 고유하게 만들고 더 높은 온도를 사용하세요.

반복 토큰 문제

반복되는 출력 토큰이 표시되면 다음 제안사항을 시도하여 줄이거나 없애세요.

설명 원인 권장 해결 방법
마크다운 표의 반복되는 하이픈 이는 모델이 시각적으로 정렬된 마크다운 테이블을 만들려고 할 때 테이블의 콘텐츠가 긴 경우에 발생할 수 있습니다. 하지만 마크다운의 정렬은 올바른 렌더링에 필요하지 않습니다.

프롬프트에 요청 사항을 추가하여 모델에 마크다운 테이블을 생성하기 위한 구체적인 가이드라인을 제공합니다. 이러한 가이드라인을 따르는 예시를 제공합니다. 온도를 조정해 볼 수도 있습니다. 코드 또는 마크다운 테이블과 같이 매우 구조화된 출력을 생성하는 경우 높은 온도 (>= 0.8)가 더 효과적인 것으로 나타났습니다.

다음은 이 문제를 방지하기 위해 프롬프트에 추가할 수 있는 가이드라인의 예입니다. 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
마크다운 표의 반복 토큰 반복되는 하이픈과 마찬가지로, 모델이 표의 콘텐츠를 시각적으로 정렬하려고 할 때 발생합니다. 마크다운의 정렬은 올바른 렌더링에 필요하지 않습니다.
  • 시스템 프롬프트에 다음과 같은 요청 사항을 추가해 보세요. 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • 온도를 조정해 보세요. 온도가 높을수록 (>= 0.8) 일반적으로 출력에서 반복 또는 중복을 제거하는 데 도움이 됩니다.
구조화된 출력의 반복되는 줄바꿈 (\n) 모델 입력에 유니코드 또는 이스케이프 시퀀스(예: \u 또는 \t)가 포함된 경우 줄바꿈이 반복될 수 있습니다.
  • 프롬프트에서 금지된 이스케이프 시퀀스를 확인하고 UTF-8 문자로 바꿉니다. 예를 들어 JSON 예시의 \u 이스케이프 시퀀스로 인해 모델이 출력에서도 이를 사용할 수 있습니다.
  • 허용되는 이스케이프에 대해 모델에 안내합니다. 다음과 같이 시스템 요청 사항을 추가합니다. 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
구조화된 출력을 사용할 때 반복되는 텍스트 모델 출력의 필드 순서가 정의된 구조화된 스키마와 다른 경우 텍스트가 반복될 수 있습니다.
  • 프롬프트에서 필드 순서를 지정하지 마세요.
  • 모든 출력 필드를 필수로 설정합니다.
반복적인 도구 호출 이는 모델이 이전 사고의 컨텍스트를 잃거나 강제로 사용할 수 없는 엔드포인트를 호출하는 경우에 발생할 수 있습니다. 사고 과정 내에서 상태를 유지하도록 모델에 지시합니다. 시스템 요청 사항 끝에 다음을 추가합니다. 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
구조화된 출력에 포함되지 않는 반복적인 텍스트 이는 모델이 해결할 수 없는 요청에 멈춰 있는 경우에 발생할 수 있습니다.
  • 사고 모드가 사용 설정된 경우 요청 사항에서 문제를 해결하는 방법에 관한 명시적인 지시를 내리지 마세요. 최종 출력을 요청하기만 하면 됩니다.
  • 0.8 이상의 높은 강도를 사용해 보세요.
  • '간결하게', '반복하지 않기' 또는 '답변을 한 번만 제공'과 같은 요청 사항을 추가합니다.

프로젝트가 제한되었거나 사용할 수 없음

API 요청에서 403 PERMISSION_DENIED ('프로젝트의 액세스가 거부되었습니다')가 반환되거나 프로젝트 상태가 Google AI Studio에서 제한됨, 무료 등급을 사용할 수 없음, 결제 필요 또는 사용할 수 없음으로 표시되는 경우 다음 섹션 중 프로젝트에 해당하는 섹션을 확인하세요.

Gemini API 무료 등급 사용 불가

일부 Google Cloud 프로젝트 또는 계정은 Gemini API 무료 등급을 사용할 수 없습니다. 프로젝트에서 무료 등급을 사용할 수 없는 경우:

  • 동일한 프로젝트에서 새 API 키를 만들어도 오류가 해결되지 않습니다. Google은 Google Cloud 프로젝트 수준에서 자격 요건을 평가합니다.
  • 이 프로젝트에서 Gemini API를 사용하려면 활성 Cloud Billing 계정을 연결하여 유료 등급으로 업그레이드해야 합니다.
  • 참고: 프로젝트를 유료 등급으로 업그레이드해도 무료 등급 할당량은 잠금 해제되지 않습니다. Google은 Gemini API 가격 책정에 따라 유료 등급 사용량을 청구하거나 요건을 충족하는 Google Cloud 크레딧에서 차감합니다.

Cloud Billing 계정 결제 필요

프로젝트가 이미 Cloud Billing 계정에 연결되어 있고 결제 필요가 표시되거나 미결제 잔액을 인용하는 403 PERMISSION_DENIED가 반환되는 경우:

  • AI Studio 결제 페이지 또는 Google Cloud Billing 콘솔로 이동하여 연체 잔액을 해결하거나 결제 수단을 업데이트하세요.
  • 결제 계정이 양호한 상태가 되면 프로젝트에서 API 액세스 권한을 자동으로 다시 얻습니다.

유출되거나 차단된 API 키

403 PERMISSION_DENIED 오류 상태에 API 키가 유출되거나 차단된 것으로 보고되었다고 표시되는 경우:

  • AI Studio API 키 페이지로 이동하여 새 API 키를 생성하고 애플리케이션 사용자 인증 정보를 업데이트합니다.
  • 클라이언트 측 코드나 공개 저장소에 API 키를 직접 삽입하지 마세요.

프로젝트 또는 결제 계정 정책 정지

정책 위반으로 인해 Google에서 Google Cloud 프로젝트 또는 Cloud Billing 계정을 정지하는 경우 연결된 이메일 주소를 확인하세요. Google Cloud 콘솔을 방문하여 정지 알림을 검토하고 프로젝트 정지 가이드라인을 따르세요.

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

이 섹션에서는 Gemini API 키가 차단되었는지 확인하는 방법과 이에 대한 조치를 설명합니다.

키가 차단된 이유 이해하기

일부 API 키가 공개적으로 노출되었을 수 있는 취약점이 확인되었습니다. 데이터를 보호하고 무단 액세스를 방지하기 위해 Google은 유출된 것으로 알려진 이러한 키가 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 키를 발급하는 방향으로 전환하고 있습니다. 이렇게 하면 의도하지 않은 교차 키 사용을 방지할 수 있습니다.
  • Google은 유출되어 Gemini API와 함께 사용되는 API 키를 기본적으로 차단하여 비용 및 애플리케이션 데이터의 악용을 방지합니다.
  • Google AI Studio에서 API 키의 상태를 확인할 수 있으며, API 키가 유출된 것으로 확인되면 즉시 조치를 취할 수 있도록 사전에 연락을 드릴 예정입니다.

모델 출력 개선

더 높은 품질의 모델 출력을 얻으려면 더 구조화된 프롬프트를 작성해 보세요. 프롬프트 엔지니어링 가이드 페이지에서는 시작하는 데 도움이 되는 몇 가지 기본 개념, 전략, 권장사항을 소개합니다.

토큰 한도 이해하기

토큰 가이드를 읽고 토큰을 계산하는 방법과 토큰 한도를 자세히 알아보세요.

알려진 문제

  • API는 일부 언어만 지원합니다. 지원되지 않는 언어로 프롬프트를 제출하면 예기치 않은 응답이 생성되거나 응답이 차단될 수 있습니다. 업데이트는 사용 가능한 언어를 참조하세요.

버그 신고

궁금한 점이 있으면 Google AI 개발자 포럼에서 토론에 참여하세요.