Gemini CLI를 거의 안 썼는데 한도 초과? Code Assist 공유 쿼터 진단법

CLI를 살짝 썼을 뿐인데 "사용량 한도 도달"이 떴습니다. 계정을 바꾸고 싶은 유혹이 드는 순간이죠. 하지만 대부분의 경우 범인은 계정이 아니라 어느 쿼터를 쓰고 있었는지에 대한 오해입니다. Gemini 제품군의 한도는 로그인 방식과 구독에 따라 달라지고, 일부 제품들 사이에서는 공유됩니다. 진단이 먼저고, 해법은 그다음입니다.

먼저: 어떤 계량기에 붙어 있는지 확인하라

같은 "Gemini CLI"라도 인증 방식에 따라 완전히 다른 쿼터에 붙습니다. Google의 공식 문서가 밝히는 구조는 이렇습니다 (Gemini CLI, "Quotas and pricing", 2026-09-17 확인):

여기서 흔한 혼동이 나옵니다. 소비자용 Gemini 웹·앱 구독(Gemini for Workspace 플랜 등)은 CLI를 구동하는 API 사용량에 적용되지 않습니다 — Google이 문서에서 명시적으로 분리해 놓은 사항입니다. "웹에서는 무제한인데 CLI는 왜 끊기지?"의 답이 여기 있습니다. 두 표면이 다른 계량기에 붙어 있습니다.

왜 '안 썼는데' 소진됐나 — 공유의 세 가지 축

축 1: CLI와 Code Assist 에이전트 모드의 쿼터는 합산됩니다. Google Cloud 문서의 표현을 그대로 빌리면: "에이전트 모드 또는 Gemini CLI의 요청 쿼터는 합산됩니다" (Google Cloud, "Quotas and limits", 2026-09-17 확인). 같은 Google 계정으로 IDE 확장에서 Code Assist를 쓰고, 터미널에서 CLI를 쓰고, 어딘가 스크립트가 에이전트 모드를 돌리고 있다면 — 세 곳이 하나의 일일 풀을 마시고 있습니다. CLI 창만 보고 "나는 별로 안 썼는데"라고 판단하면 안 되는 이유입니다.

축 2: 프롬프트 하나가 요청 여러 개. 같은 문서가 명시합니다: "에이전트 모드나 Gemini CLI에서는 프롬프트 하나가 여러 모델 요청으로 이어질 수 있습니다." 파일을 읽고, 수정하고, 검증하는 에이전트 루프에서 프롬프트 하나가 실제로는 하루 할당량의 몇 퍼센트를 쓰는지는 별도 글에서 다룹니다 — 여기서 중요한 건 "오늘 프롬프트 3개 썼는데 왜 40 요청이나?"가 정상이라는 점입니다.

축 3: 요청 수와 분당 요율은 별개. 요청 한도는 사용자당·분당으로도 제한되고 "서비스 수요가 높을 때의 가용성에 좌우됩니다" (같은 문서). 즉 한도 도달 메시지가 항상 일일 풀 소진을 뜻하지 않을 수 있습니다 — 바쁜 시간대의 일시적 요율 차단일 수도 있습니다. 이 둘의 구분이 아래 체크리스트의 핵심입니다.

진단 체크리스트 (이 순서대로)

1. 오류 문구를 있는 그대로 기록하세요. 재입력 전에: 정확한 메시지, 시각, 무슨 작업 중이었는지. API 키를 쓰는 환경이면 키 문자열·프로젝트 ID 같은 자격 증명은 반드시 가리고 저장하세요. 나중에 지원 요청이나 재현에 필요한 유일한 증거입니다.
2. 인증 경로를 특정하세요. CLI에서 /about(또는 계정 정보 표시 명령)으로 어떤 계정·방식으로 로그인했는지 확인 — 개인 Google 계정인지, Workspace 계정인지, API 키인지. 위 표에서 자기 행을 찾는 것이 모든 판단의 기준입니다.
3. /stats model로 세션 사용량 확인. CLI 공식 문서가 안내하는 명령으로 현재 세션의 토큰 사용량과 현재 쿼터에 연관된 한도를 볼 수 있습니다 (같은 문서, 2026-09-17 확인).
4. 시간을 기록하고 짧게 재시도하세요. 몇 분 뒤 풀리면 분당 요율 차단이었을 가능성이 높습니다(분당 제한은 매분 리셋). 몇 시간이 지나도 같으면 일일 풀 문제일 가능성이 높습니다 — 일일 요청 한도는 Google이 정한 시각에 리셋되며, 정확한 리셋 시각을 문서가 보장하지 않으니 여러분이 기록한 시각이 유일한 근거입니다.
5. 같은 계정을 쓰는 다른 표면을 점검하세요. 같은 Google 계정의 IDE 확장, 다른 기기의 CLI, CI의 스크립트. 하나의 일일 풀을 함께 쓰는 것들이 오늘 얼마나 썼는지 합산해서 보세요.
6. 그래도 숫자가 수상하면 로컬 상태부터 재확인. 계정을 돌려치기 전에, 같은 인증으로 재로그인해 상태를 다시 읽게 하세요. 계정 로테이션이나 쿼터 우회 시도는 약관 위반이고 이 글의 권장이 아닙니다.

자주 하는 실수

• 소비자 구독이 API 크레딧이라고 착각. Gemini 웹앱의 구독과 CLI·API 계량은 문서상 분리되어 있습니다. 구독 업그레이드는 CLI 로그인 경로의 일일 요청 상한을 올리는 것이지, API 키 경로에 크레딧을 채우는 게 아닙니다.
• 429를 단일 의미로 읽기. API 키 경로에서 429는 분당 요청·토큰 한도일 수도 있고 일일 요청 수·지출 기반 한도일 수도 있습니다. Google의 API 문서는 세 가지 차원(RPM/TPM/RPD) 중 하나만 넘겨도 오류가 난다고 설명하며, 일일 쿼터는 태평양 시간 자정에 리셋됩니다 (Google AI, "Rate limits", 2026-09-17 확인).
• 남의 숫자 믿기. 이 카테고리의 한도는 자주 바뀝니다. 6개월 전 포럼 글의 요청 수보다, 지금 세션의 /stats 출력이 항상 우선입니다.

제자리로 돌아오면

진단이 끝났으면 다음 중 하나가 남습니다: 요율 차단이었다면 재시도 간격 두기, 일일 풀이 문제라면 작업 시간 분산이나 라우팅 조정, 그리고 무엇보다 작업이 멈추지 않게 할 대안 경로 하나 — 다른 에이전트로 작업을 안전하게 넘기는 법이 그 방법론입니다.

meshcode는 각 에이전트를 자기 인증·자기 한도 안의 병렬 창으로 연결하므로, 한 창이 일일 쿼터를 채우면 같은 노트로 다음 창에서 이어갈 수 있습니다.

관련 글: Gemini 사용량 한도의 전체 구조 · 프롬프트 하나에 요청이 여러 번 드는 이유 · Claude Code 한도에서의 인계.

👉 meshcode 다운로드