이 가이드를 사용하여 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 스튜디오에서 프로젝트에 결제를 사용 설정하세요. | 무료 등급이 지원되지 않는 리전에서 요청을 하고 있으며 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 스튜디오의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요. |
| 503 | 현재 구매할 수 없음 | 서비스에 일시적으로 과부하가 발생했거나 다운되었을 수 있습니다. | 서비스의 용량이 일시적으로 부족합니다. | 일시적으로 다른 모델 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로)로 전환하고 작동하는지 확인합니다. 또는 잠시 기다렸다가 요청을 다시 시도해 보세요. 다시 시도해도 문제가 지속되면 Google AI 스튜디오의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요. |
| 504 | DEADLINE_EXCEEDED | 서비스가 기한 내에 처리를 완료할 수 없습니다. | 프롬프트 (또는 컨텍스트)가 너무 커서 제때 처리할 수 없습니다. | 이 오류를 방지하려면 클라이언트 요청에서 'timeout'을 더 크게 설정하세요. |
API 호출에서 모델 매개변수 오류 확인
모델 매개변수가 다음 값 내에 있는지 확인합니다.
| 모델 매개변수 | 값 (범위) |
| 후보 수 | 1~8 (정수) |
| 온도 | 0.0~1.0 |
| 최대 출력 토큰 |
get_model (Python)를 사용하여 사용 중인 모델의 최대 토큰 수를 결정합니다.
|
| TopP | 0.0~1.0 |
매개변수 값을 확인하는 것 외에도 올바른 API 버전 (예: /v1 또는 /v1beta) 및 필요한 기능을 지원하는 모델을 선택합니다. 예를 들어 기능이 베타 버전인 경우 /v1beta API 버전에서만 사용할 수 있습니다.
올바른 모델인지 확인
모델 페이지에 나열된 지원되는 모델을 사용하고 있는지 확인합니다.
2.5 모델에서 지연 시간 또는 토큰 사용량이 증가함
2.5 Flash 및 Pro 모델에서 지연 시간 또는 토큰 사용량이 더 높다면 품질을 개선하기 위해 생각이 기본적으로 사용 설정되어 있기 때문일 수 있습니다. 속도를 우선하거나 비용을 최소화해야 하는 경우 생각을 조정하거나 사용 중지할 수 있습니다.
안내와 샘플 코드는 사고 페이지를 참고하세요.
안전 문제
API 호출의 안전 설정으로 인해 메시지가 차단된 경우 API 호출에 설정한 필터와 관련하여 메시지를 검토합니다.
BlockedReason.OTHER이 표시되면 쿼리 또는 응답이 서비스 약관을 위반했거나 지원되지 않는 것입니다.
재진술 문제
RECITATION 이유로 인해 모델이 출력 생성을 중지하는 경우 모델 출력이 특정 데이터와 유사할 수 있습니다. 이 문제를 해결하려면 프롬프트 / 맥락을 최대한 고유하게 만들고 더 높은 온도를 사용하세요.
모델 출력 개선
더 나은 품질의 모델 출력을 위해 더 구조화된 프롬프트를 작성해 보세요. 프롬프트 엔지니어링 가이드 페이지에서는 시작하는 데 도움이 되는 몇 가지 기본 개념, 전략, 권장사항을 소개합니다.
적절한 입력-출력 쌍의 예가 수백 개 있는 경우 모델 조정을 고려해 볼 수도 있습니다.
토큰 한도 이해하기
토큰 가이드를 읽고 토큰 수를 집계하는 방법과 한도에 관해 자세히 알아보세요.
알려진 문제
- 이 API는 일부 언어만 지원합니다. 지원되지 않는 언어로 프롬프트를 제출하면 예상치 못한 응답이나 차단된 응답이 발생할 수 있습니다. 사용 가능한 언어에서 업데이트를 확인하세요.
버그 신고
궁금한 점이 있으면 Google AI 개발자 포럼에서 토론에 참여하세요.