문제 해결 가이드

이 가이드를 사용하여 Gemini API를 호출합니다 개략적으로는 둘 중 하나에서 Gemini API 백엔드 서비스 또는 클라이언트 SDK에서 사용할 수 있습니다 Google의 클라이언트 SDK는 오픈소스로 제공됩니다.

API 키 문제가 발생하면 API 키 설정 가이드에 따라 API 키를 올바르게 설정해야 합니다.

Gemini API 백엔드 서비스 오류 코드

다음 표에는 발생할 수 있는 일반적인 백엔드 오류 코드와 함께 원인 및 문제 해결 단계를 확인하세요.

HTTP 코드	상태	설명	예	해결 방법
400	INVALID_ARGUMENT	요청 본문 형식이 잘못되었습니다.	요청에 오타가 있거나 필수 입력란이 누락되었습니다.	요청 형식, 예시, 지원되는 버전은 API 참조를 확인하세요. 최신 API 버전의 기능을 이전 엔드포인트와 함께 사용하면 오류가 발생할 수 있습니다.
400	FAILED_PRECONDITION	거주 중인 국가에서는 Gemini API 무료 등급을 사용할 수 없습니다. Google AI Studio에서 프로젝트에 결제를 사용 설정하세요.	무료 등급이 지원되지 않는 리전에서 요청을 하고 있으며 Google AI Studio에서 프로젝트에 결제를 사용 설정하지 않았습니다.	Gemini API를 사용하려면 Google AI Studio를 사용하여 유료 요금제를 설정해야 합니다.
403	PERMISSION_DENIED	API 키에 필요한 권한이 없습니다.	잘못된 API 키를 사용하고 있습니다. 나 적절한 인증을 거치지 않고 조정된 모델을 사용하려고 하는 경우	API 키가 설정되어 있고 올바른 액세스 권한이 있는지 확인하세요. 또한 조정된 모델을 사용하려면 적절한 인증을 거쳐야 합니다.
404	NOT_FOUND	요청한 리소스를 찾을 수 없습니다.	요청에 참조된 이미지, 오디오 또는 동영상 파일을 찾을 수 없습니다.	API 버전에 대해 요청의 모든 매개변수가 유효한지 확인합니다.
429	RESOURCE_EXHAUSTED	비율 제한을 초과했습니다.	무료 등급 Gemini API로 분당 너무 많은 요청을 전송하고 있습니다.	모델의 비율 제한 내에 있는지 확인합니다. 필요한 경우 할당량 증가를 요청합니다.
500	내부	Google 측에서 예기치 않은 오류가 발생했습니다.	입력 컨텍스트가 너무 깁니다.	입력 컨텍스트를 줄이거나 일시적으로 다른 모델로 전환 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로 전환)하여 작동하는지 확인해 보세요. 또는 잠시 기다렸다가 요청을 다시 시도하세요. 다시 시도해도 문제가 지속되면 Google AI Studio의 의견 보내기 버튼을 사용하여 신고해 주세요.
503	현재 구매할 수 없음	서비스가 일시적으로 과부하되거나 다운될 수 있습니다.	서비스 용량이 일시적으로 부족합니다.	일시적으로 다른 모델로 전환 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로 전환)하여 작동하는지 확인합니다. 또는 잠시 기다렸다가 요청을 다시 시도하세요. 다시 시도해도 문제가 지속되면 Google AI Studio의 의견 보내기 버튼을 사용하여 신고해 주세요.
504	DEADLINE_EXCEEDED	서비스에서 기한 내에 처리를 완료할 수 없습니다.	프롬프트 (또는 맥락)가 너무 커서 시간 내에 처리할 수 없습니다.	더 긴 '시간 제한' 설정 이 오류를 피할 수 있습니다.

Python 클라이언트 SDK 오류 코드

다음 표에는 Python 클라이언트 SDK 오류 발생할 수 있는 코드와 그 원인에 대한 설명:

예외/오류 유형	클래스	설명
BlockedPromptException	google.generativeai.types.BlockedPromptException	안전상의 이유로 메시지가 차단되었습니다.
BrokenResponseError	google.generativeai.types.BrokenResponseError	스트리밍 응답이 손상되었습니다. 채팅 기록과 같이 전체 응답이 필요한 항목에 액세스할 때 발생합니다. 스택 트레이스에 제공된 오류 세부정보를 참고하세요.
IncompleteIterationError	google.generativeai.types.IncompleteIterationError	완전한 API 응답이 필요하지만 스트리밍 응답이 완전히 반복되지 않은 항목에 액세스하는 경우 발생합니다. 응답 객체에서 `resolve()`를 호출하여 반복자를 사용합니다.
StopCandidateException	google.generativeai.types.StopCandidateException	API는 예외적인 `finish_reason`로 응답했습니다. 이유를 확인하여 진행 방법에 대한 안내를 확인하세요.
PermissionDenied	google.api_core.exceptions.PermissionDenied	요청된 리소스 (예: 모델)에 대한 권한이 없습니다.
ResourceExhausted	google.api_core.exceptions.ResourceExhausted	할당량이 소진되었습니다. 잠시 후 다시 시도해 주세요. 이러한 오류를 처리하려면 자동 재시도를 설정하는 것이 좋습니다.
AlreadyExists	google.api_core.exceptions.AlreadyExists	ID가 동일한 조정된 모델이 이미 있습니다. 새 모델을 조정할 때 고유한 모델 ID를 지정하세요.
InvalidArgument	google.api_core.exceptions.InvalidArgument	잘못된 인수입니다. 한 가지 예는 파일이 너무 커서 페이로드 크기 제한을 초과하는 것입니다. 다른 하나는 잘못된 API 키를 제공하는 것입니다.
DefaultCredentialsError	google.auth.exceptions.DefaultCredentialsError	인증에 실패했습니다. API 키를 확인한 후 다시 시도해 주세요.
RetryError	google.api_core.exceptions.RetryError	gRPC를 지원하지 않는 프록시를 사용하는 경우 발생할 수 있습니다. `genai.configure(..., transport="rest")`로 REST 전송을 사용해 보세요.

API 호출에서 모델 매개변수 오류 확인

모델 매개변수가 다음 값 내에 있는지 확인합니다.

모델 매개변수	값 (범위)
후보자 수	1~8 (정수)
온도	0.0~1.0
최대 출력 토큰	사용 `get_model` (Python) 를 사용하여 사용 중인 모델의 최대 토큰 수를 결정합니다.
TopP	0.0~1.0

매개변수 값을 확인하는 것 외에도 올바른 API 버전 (예: /v1 또는 /v1beta) 및 지원하는 모델을 빌드해야 합니다 예를 들어 기능이 베타 버전인 경우 /v1beta API 버전에서만 사용할 수 있습니다.

올바른 모델이 있는지 확인

다음에 나열된 지원되는 모델을 사용하고 있는지 확인하세요. 모델 페이지를 참조하세요.

안전 문제

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

BlockedReason.OTHER이(가) 표시되면 쿼리 또는 응답이 약관을 위반한 것일 수 있습니다. 서비스 또는 기타 지원되지 않을 수 있습니다.

인용 문제

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

모델 출력 개선

모델 출력을 개선하려면 더 정형화된 프롬프트를 작성해 보세요. 이 프롬프트 설계 소개 페이지에서는 시작하는 데 도움이 되는 몇 가지 기본 개념, 전략 및 권장사항을 확인하세요.

좋은 입출력 쌍의 예시가 수백 개 있는 경우 모델 조정을 고려하세요.

토큰 한도 이해하기

토큰 가이드에서 방법을 자세히 알아보세요. 토큰과 토큰의 한도를 계산할 수 있습니다.

알려진 문제

API는 일부 언어만 지원합니다. 프롬프트 제출 지원되지 않는 언어는 예기치 않거나 차단되는 응답을 생성할 수 있습니다. 자세한 내용은 지원되는 언어를 참고하세요.

버그 신고

Google AI 개발자 포럼에서 토론에 참여하세요. 에 문의하세요.