제미나이 API 429 오류 해결법은 요청 한도를 확인하고, 초과한 제한에 맞춰 재시도를 설정하는 순서에서 시작한다. 잠깐 기다리면 풀리는 분당 제한과 초기화까지 기다려야 하는 일일 할당량은 대응이 다르다. 오류가 발생할 때마다 API 키를 바꾸거나 호출을 반복하면 원인 파악이 더 어려워진다.
📌 핵심 요약
- Google AI Studio에서 실제 프로젝트와 모델의 RPM·TPM·RPD를 먼저 확인한다.
- 분당 제한에는 호출 분산과 지수 백오프를 적용하고, 일일 한도에는 초기화 대기 또는 증액 요청으로 대응한다.
- SDK 자동 재시도를 확인한 뒤 추가 재시도를 설정해야 호출이 중복 증폭되는 문제를 줄일 수 있다.
1. 제미나이 API 429 오류에서 먼저 구분할 요청 한도
429 RESOURCE_EXHAUSTED는 요청을 처리하는 데 필요한 할당량이나 제한에 걸렸다는 신호다. HTTP 상태 코드만 보고 대기 시간을 정하기보다, 응답 본문에 나온 제한 항목과 메시지를 함께 읽어야 한다. 같은 429라도 분당 요청 수, 입력 토큰, 일일 요청량 또는 비용 기반 한도 중 무엇이 원인인지에 따라 해결 방향이 달라진다.
Google의 주요 제한 지표는 RPM은 분당 요청 수, TPM은 분당 입력 토큰 수, RPD는 일일 요청 수다. 각각 독립적으로 평가되므로 한 항목만 초과해도 제한 오류가 발생한다. 모델과 사용 등급에 따라 값이 달라지므로 인터넷에 게시된 특정 숫자를 모든 계정의 공통 한도로 적용하면 안 된다.
| 제한 항목 | 확인할 상황 | 우선 대응 |
|---|---|---|
| RPM | 짧은 시간에 요청이 몰리는지 확인 | 요청 간격 확보, 동시 호출 축소 |
| TPM | 긴 문서·대화 이력이 반복 전송되는지 확인 | 입력 축소, 큰 요청의 실행 시점 분산 |
| RPD | 하루 누적 호출이 한도에 도달했는지 확인 | 초기화 대기, 증액 요청 검토 |
TPM 대응에서는 입력과 출력을 구분하는 것이 중요하다. 분당 입력 토큰 한도에 걸렸다면 출력 길이만 줄여서는 직접적인 원인이 해소되지 않는다. 불필요한 대화 기록을 덜어내거나, 같은 분에 처리하는 문서의 총입력량을 낮추는 조정이 먼저다.
1. 제미나이 API 429 오류에서 먼저 구분할 요청 한도 실시간 확인하기
2. Google AI Studio에서 프로젝트·모델별 실제 한도 확인하기
확인 순서는 실제 호출 프로젝트 → 모델 이름 → 사용 등급 → 제한 항목이다. 개발 환경과 운영 환경이 서로 다른 프로젝트를 사용하면, 화면에서 보고 있는 한도와 실제 오류가 발생한 한도가 일치하지 않을 수 있다. 오류 로그의 호출 시각도 함께 기록하면 순간적인 집중 호출을 찾기 쉽다.
- 프로젝트를 맞춘다. 애플리케이션의 API 키가 어느 Google Cloud 프로젝트에 연결되어 있는지 확인한다. 키 값 자체는 로그에 남기지 않는다.
- Google AI Studio의 활성 한도를 확인한다. 해당 프로젝트에서 사용하는 모델과 사용 등급에 적용되는 제한을 읽는다.
- 모델 식별자를 대조한다. 설정 파일의 모델 이름과 한도 화면의 대상 모델이 같은지 확인한다. 프리뷰·실험 모델은 제한이 더 엄격할 수 있다.
- 오류 발생 구간의 호출을 모은다. 웹 서버, 배치 작업, 테스트 스크립트에서 같은 프로젝트로 발생한 요청을 함께 살핀다.
한도는 API 키가 아니라 프로젝트 단위로 적용된다. 같은 프로젝트에서 새 키를 만들더라도 프로젝트의 사용량이 초기화되거나 한도가 추가되는 것은 아니다. 여러 서버가 키를 나눠 사용해도 같은 프로젝트에 속한다면 합산된 트래픽을 기준으로 제한을 확인해야 한다.
운영 관점에서는 키 교체보다 요청을 한곳에서 조절하는 구조가 효과적이다. 개별 서버는 여유가 있다고 판단해도 전체 호출량은 한도를 넘을 수 있기 때문이다. 이는 프로젝트 단위 제한을 바탕으로 한 설계 판단이며, 요청 큐나 공통 속도 제한기를 두면 여러 작업의 호출 시점을 함께 조정할 수 있다.
Google AI Studio 프로젝트별 API 요청 한도 실시간 확인하기
3. 분당 제한·일일 할당량·비용 기반 429 오류별 대응
분당 요청·토큰 제한은 대기와 호출 분산부터 적용
RPM이나 TPM 초과가 확인되면 신규 요청 속도를 낮추고, 잠시 기다린 뒤 제한된 횟수만 재시도한다. 동시에 실행하는 작업 수를 줄이고 요청을 시간에 걸쳐 분산하면 재시도 자체가 덜 필요해진다. 실패한 요청을 즉시 같은 속도로 다시 보내는 방식은 혼잡을 해소하기 어렵다.
일일 요청 한도는 태평양 시간 자정 기준으로 확인
RPD는 태평양 시간 자정에 초기화된다. 한국 시간 자정을 기준으로 다시 호출하면 여전히 같은 일일 집계 구간일 수 있으며, 태평양 지역의 서머타임 적용 여부에 따라 한국 시간 환산도 달라진다. 일일 할당량을 소진한 상태에서는 몇 초 간격의 반복 재시도보다 초기화 대기 또는 할당량 증액 요청이 맞는 대응이다.
2026년 확인할 추가 항목은 이동식 10분 비용 한도
2026년 확인한 Google 공식 문서는 요청·토큰 제한 외에 비용 기반 제한도 안내한다. 적용 대상 계정의 한도는 이동식 10분 구간에 Tier 1은 10달러, Tier 2는 50달러, Tier 3은 200달러이며, 초과 시 429 오류가 반환된다. 적용 여부는 결제 이력과 계정 상태 등에 따라 달라지므로 모든 유료 계정에 동일하게 적용된다고 단정하면 안 된다.
이 수치는 월 예산이나 하루 지출 한도가 아니다. 이동식 구간이므로 매시 정각이나 10분 단위의 고정 시점에 일괄 초기화된다고 해석해서도 안 된다. 해당 제한이 원인이라면 고비용 요청의 속도와 문맥 길이·출력 길이를 조정하고, 정상 사용 중에도 반복되면 증액을 검토한다.
근거: [Google 공식 요청 한도 문서](https://ai.google.dev/gemini-api/docs/rate-limits), [Google 공식 API 오류 안내](https://ai.google.dev/gemini-api/docs/api-errors). 모델별 실제 수치는 Google AI Studio의 활성 한도를 기준으로 확인한다.
3. 분당 제한·일일 할당량·비용 기반 429 오류별 대응 바로가기
4. SDK 자동 재시도 확인 후 지수 백오프·지터 설정하기
추가 반복문을 작성하기 전에 SDK가 이미 재시도하는지 확인해야 한다. Google 공식 문제 해결 문서는 Python SDK가 일시적 오류를 최대 4회 자동 재시도하며, 초기 지연은 약 1초, 최대 지연은 60초라고 설명한다. 설치 버전과 사용자 설정에 따라 실제 동작을 확인하고, 최대 지연을 전체 처리 시간 제한과 혼동하지 않는 것이 좋다.
REST로 직접 호출하거나 재시도를 직접 제어한다면 지수 백오프를 적용한다. 기본 대기 시간을 1초, 2초, 4초, 8초처럼 늘리고 무작위 지연인 지터를 더하는 방식이다. 이 숫자는 대기 전략의 예시이며, 해당 시간만 기다리면 한도가 반드시 회복된다는 뜻은 아니다.
- 재시도 가능한 원인을 분류한다. 일시적인 429, 408, 5xx 등을 대상으로 하되, 일일 할당량 소진은 짧은 재시도 루프에서 제외한다.
- 대기 시간을 점차 늘린다. 실패 직후 연속 호출하지 않고, 다음 시도까지 충분한 간격을 둔다.
- 지터를 추가한다. 여러 작업이 정확히 같은 순간에 재접속하는 현상을 줄인다.
- 최대 횟수와 전체 제한 시간을 정한다. 재시도가 끝없이 이어지거나 사용자 요청이 지나치게 오래 대기하지 않도록 한다.
- 실패 결과를 보관한다. 제한에 도달한 작업은 중단하거나 큐로 넘기고, 원인과 다음 처리 상태를 남긴다.
400·402·403은 같은 요청을 그대로 자동 재시도하는 대상에서 제외한다. 잘못된 요청, 결제 잔액 부족, 권한 문제처럼 설정이나 계정 상태를 먼저 수정해야 하는 경우이기 때문이다. 오류 코드뿐 아니라 상세 메시지를 함께 보아야 잘못된 재시도 분기를 피할 수 있다.
근거: [Google 공식 문제 해결 가이드의 재시도 전략](https://ai.google.dev/gemini-api/docs/troubleshooting). 위 호출 중첩 예시는 해당 원칙을 적용한 운영상 분석이다.
4. SDK 자동 재시도 확인 후 지수 백오프·지터 설정하기
5. 반복 호출을 줄이는 운영 체크리스트와 해결 순서
오류가 사라진 뒤에는 원래 요청 속도를 한꺼번에 복구하지 않는 편이 좋다. 대기 중이던 작업이 동시에 재개되면 같은 제한에 다시 걸릴 수 있기 때문이다. 큐에서 작업을 조금씩 꺼내고 동시 실행 수를 단계적으로 늘리면 재발 원인을 확인하기 쉽다.
실무에서 중요한 지표는 재시도 성공률 하나로 끝나지 않는다. 최종 성공률과 전체 대기 시간, 실제 호출 횟수를 함께 봐야 재시도가 서비스 품질을 개선했는지 판단할 수 있다. 성공률이 높아져도 호출이 중복 증폭되거나 응답이 지나치게 늦어진다면 요청 분산과 입력량 조정이 더 시급할 수 있다.
- 로그: 발생 시각, 프로젝트 식별 정보, 모델, HTTP 상태, 상세 오류, 재시도 횟수와 대기 시간을 남긴다.
- 집계: 같은 프로젝트를 사용하는 서버와 예약 작업의 트래픽을 함께 확인한다.
- 입력: 반복 첨부되는 문서와 불필요한 대화 이력을 줄여 입력 토큰을 관리한다.
- 동시성: 여러 작업이 한꺼번에 시작되는 예약 시각과 재시도 시점을 분산한다.
- 중복 처리: 타임아웃 후 재시도할 때 결과 저장이나 후속 작업이 중복 실행되지 않도록 작업 상태를 관리한다.
- 증액 판단: 호출 구조를 조정해도 정상 트래픽이 계속 한도에 닿으면 사용 등급과 증액 절차를 검토한다.
해결 순서는 오류 상세 확인 → AI Studio 한도 대조 → 제한 종류에 맞는 대기·호출 조정 → SDK 재시도 확인 → 백오프와 최대 횟수 설정이다. 분당 제한은 요청 흐름을 조절하고, 일일 제한은 초기화 또는 증액으로 대응한다. 이 구분을 먼저 해두면 API 키 교체와 무작정 반복 호출에 쓰는 시간을 줄일 수 있다.