Gemini API에서 429 오류가 발생하는 이유
Gemini API의 429 RESOURCE_EXHAUSTED는 현재 프로젝트의 요청량·토큰량·일일 한도나 비용 보호 제한을 넘었을 때 발생할 수 있습니다. 한도는 모델·사용 단계·프로젝트 설정에 따라 달라지며, 예전 Gemini 모델의 RPM 숫자를 현재 모델에 그대로 적용하면 안 됩니다.
Google 공식 문서: 요청 한도 · 오류 해결과 재시도 권고 · AI Studio 프로젝트 사용량.
1. 오류 진단표
| 증상 | 가능한 원인 | 다음 확인 사항 |
|---|---|---|
| 429 RESOURCE_EXHAUSTED | RPM·TPM·RPD 또는 비용 제한 | 프로젝트·모델별 대시보드와 오류 본문 |
| 400 INVALID_ARGUMENT | 입력 형식·파라미터 오류 | SDK·API 버전·요청 JSON |
| 401·403 인증·권한 오류 | 키·권한·프로젝트 설정 문제 | 환경변수·키 발급 프로젝트 |
| 404 모델을 찾을 수 없음 | 모델 ID 오류 또는 제공 중단 | 현재 모델 목록과 API 버전 |
| 503 UNAVAILABLE | 일시적인 서비스 문제 | 공식 장애 안내와 제한된 재시도 |
2. 먼저 프로젝트의 현재 한도를 확인하세요
Google AI Studio의 프로젝트 대시보드에서 해당 모델의 분당 요청(RPM), 분당 토큰(TPM), 일일 요청(RPD)을 확인합니다. API 키 여러 개를 만들었다고 같은 프로젝트의 한도가 키 개수만큼 늘어나지는 않습니다. 요청 로그에 모델 ID, 시각, HTTP 상태, 요청당 입력 토큰을 기록하면 어떤 제한에 먼저 도달했는지 좁힐 수 있습니다.
3. SDK 기본 재시도와 지수 백오프
Google은 429나 503 같은 일시적 오류에 지수 백오프와 최대 재시도 횟수를 권고합니다. google-genai 등 공식 SDK는 일부 일시적 오류에 대한 기본 재시도를 제공할 수 있습니다. 직접 추가 재시도를 만들 때는 SDK 내부 재시도와 중복되어 과도한 호출이 일어나지 않도록 확인하세요.
재시도 정책 예시(의사코드)
1. HTTP 429 또는 일시적인 5xx인지 확인
2. 서버가 재시도 시간을 안내하면 우선 적용
3. 그렇지 않으면 1초 → 2초 → 4초처럼 점차 기다림
4. 동시 요청 충돌을 피하도록 약간의 무작위 지연 추가
5. 정해 둔 최대 시도 횟수를 넘으면 중단하고 운영자에게 알림잘못된 API 키, 과금 설정 오류, 입력 형식 문제는 단순히 기다려도 해결되지 않습니다. 같은 요청을 무한 반복하지 마세요.
4. 고유 실습: 가상 오류 로그 분석
다음 가상 사례에서는 분당 요청 한도가 20회인 실습 프로젝트에 21번째 요청을 보냈다고 가정합니다. 실제 본인의 한도는 다를 수 있습니다.
| 기록 | 예시 |
|---|---|
| 프로젝트 | 학습용 프로젝트 |
| 선택 모델 | 현재 AI Studio에서 지원되는 모델 ID |
| 상태 | 429 |
| 발생 직전 | 분당 요청 20건 |
| 조치 | 요청 간격 조정, 중복 요청 제거, 한도 확인 |
실제 기록에서는 비밀키와 고객이 입력한 민감정보를 로그에 남기지 않고, 동일 작업 중복 방지용 ID를 사용하세요.
5. 예방 점검표
- 429가 발생한 프로젝트와 모델을 정확히 확인합니다.
- 분당 요청과 분당 토큰을 각각 기록합니다.
- 불필요한 동일 요청 반복, 과도한 프롬프트 길이, 과도한 병렬 처리를 줄입니다.
- 필요하면 적법한 결제 설정과 사용 단계 조정을 검토합니다.
- 실시간 처리와 야간 배치 작업의 우선순위를 구분합니다.
API 키 발급부터 확인하려면 Gemini API 키 관리, 코드 실행 중 오류라면 Python 예제를 참고하세요.