Gemini API 키 한도 초과 오류, 해결 방법은?
개발자가 Google Gemini API를 사용하다가 키 한도 초과 오류를 만나 도움을 요청했습니다. 무료 티어의 분당·일일 요청 한도를 넘겼을 때 자주 발생하는 문제입니다. AI 에이전트를 만들 때 비용 없이 테스트하려는 개발자에게 실용적인 참고가 됩니다.
Google Gemini API는 무료 플랜(Free Tier)에서 분당 요청 수(RPM)와 하루 요청 수(RPD)에 상한이 있습니다. 이 한도를 넘으면 429 오류 또는 'key limit exceeded' 메시지가 반환되고 요청이 차단됩니다. 개발자는 보통 여러 API 키를 번갈아 쓰거나, 요청 사이에 짧은 대기 시간을 두거나, 유료 플랜으로 전환하는 방식으로 대응합니다. 특히 AI 에이전트처럼 짧은 시간에 반복 호출이 많은 구조에서 이 문제가 자주 나타납니다.
핵심 포인트
- Gemini 무료 플랜은 분당·일일 요청 횟수에 상한이 있어 초과 시 오류가 발생한다
- 오류 코드 429는 '너무 많은 요청'을 의미하며, 잠시 기다리면 자동으로 해제된다
- 여러 API 키를 번갈아 사용하거나 요청 간격을 늘리면 한도 초과를 피할 수 있다
- 장기적으로 트래픽이 많다면 유료 플랜(Pay-as-you-go) 전환을 고려해야 한다
- AI 에이전트 설계 시 재시도 로직(exponential backoff)을 넣으면 한도 오류에 자동 대응 가능하다
용어 한 줄 설명
- Gemini API
- 개발자가 자기 앱이나 서비스에서 Gemini를 부를 수 있게 해 주는 연결 방식입니다.
- 무료 티어
- 서비스 업체가 일정량까지 무료로 제공하는 사용 한도입니다.
- AI 에이전트
- 사람 대신 정보를 찾거나 작업을 처리하도록 만든 AI 프로그램입니다.
- Free Tier
- API를 무료로 쓸 수 있는 기본 플랜으로, 사용량에 제한이 있다
- 429 오류
- 서버가 '요청이 너무 많다'고 거부할 때 반환하는 HTTP 상태 코드
- API 키
- 앱이나 서비스가 다른 서비스에 접속할 때 쓰는 비밀 열쇠 같은 값입니다.
- 오류 코드
- 컴퓨터 프로그램에 문제가 생겼을 때 무엇이 잘못되었는지 알려주는 숫자입니다.
- exponential backoff
- 오류 발생 시 재시도 간격을 점점 늘려가며 서버 부하를 줄이는 방법