Gemini AI Studio 오류 7가지 해결법 — API 키·할당량·429 에러 실전 가이드

Gemini AI Studio로 자동화 돌리시는데 갑자기 429나 SAFETY 차단 떠서 당황하셨죠?

저도 그랬어요. n8n 워크플로 12개 돌리는 중에 매 시간 한 번씩 멈춰서, 한 달 동안 Google Cloud Console·Stack Overflow 뒤지면서 패턴을 정리했거든요. 결론부터 말씀드리면, 7가지 오류만 알면 95% 자동 복구 가능해요.

오늘은 Gemini 2.5 Pro AI Studio 운영하면서 가장 자주 만나는 오류 7가지와 즉시 적용할 코드 예시까지 정리할게요. 5월 3일 기준 Google 공식 문서 + 실측 데이터 기반입니다.

1. RESOURCE_EXHAUSTED 429 — 무료 티어 5 RPM 한도

가장 흔한 오류예요. 메시지: "You have exceeded your current quota, please check your plan and billing details."

원인: Gemini 2.5 Pro 무료 티어는 분당 5건(RPM), 일 50건(RPD) 한도. 자동화 돌리면 한 시간도 안 되어 한도 초과.

해결 코드:

import google.generativeai as genai
import time
from google.api_core import retry

genai.configure(api_key="YOUR_KEY")
model = genai.GenerativeModel("gemini-2.5-pro")

@retry.Retry(predicate=retry.if_exception_type(
    Exception
), initial=2.0, maximum=60.0, multiplier=2.0, deadline=300.0)
def generate_with_retry(prompt):
    response = model.generate_content(prompt)
    return response.text

# 분당 5건 한도 강제 (12초 간격)
for prompt in prompts:
    print(generate_with_retry(prompt))
    time.sleep(12)

근본 해결: Tier 1 결제(신용카드 등록) 후 분당 1000건으로 한도 상승. Pro 모델 입력 토큰 가격은 100만 토큰당 1.25달러(200K 컨텍스트 이하 기준).

2. API_KEY_INVALID — 환경변수 공백 문제

증상: "API key not valid. Please pass a valid API key." 메시지가 정확한 키 입력했는데도 뜨는 경우.

원인 3가지:

• 키 앞뒤 공백 또는 따옴표가 .env 파일에 같이 저장됨
• Google Cloud 프로젝트에서 Generative Language API 비활성화
• Cloud Console에서 키 IP 제한 걸려있음

해결:

# 키 정확히 확인 (공백 제거)
echo "${GEMINI_API_KEY}" | wc -c
# 기대값: 40 (마지막 개행 제외 39)

# Generative Language API 활성화 확인
gcloud services list --enabled | grep generativelanguage

키 앞뒤 공백이 가장 흔한 함정이에요. .env 파일에 GEMINI_API_KEY="AIzaSy..." 처럼 따옴표 넣지 마시고 GEMINI_API_KEY=AIzaSy... 형태로만.

3. 안전 필터(SAFETY) 차단 — 무해한 콘텐츠도 막힘

Gemini는 기본 4가지 카테고리에서 medium 이상이면 응답을 차단해요. 의료·법률·역사 콘텐츠가 자주 걸립니다.

해결: safetySettings로 카테고리별 임계값 조정.

from google.generativeai.types import HarmCategory, HarmBlockThreshold

safety_settings = [
    [HarmCategory.HARM_CATEGORY_HARASSMENT, HarmBlockThreshold.BLOCK_ONLY_HIGH],
    [HarmCategory.HARM_CATEGORY_HATE_SPEECH, HarmBlockThreshold.BLOCK_ONLY_HIGH],
    [HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, HarmBlockThreshold.BLOCK_ONLY_HIGH],
    [HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, HarmBlockThreshold.BLOCK_ONLY_HIGH],
]

response = model.generate_content(
    prompt,
    safety_settings=dict(safety_settings)
)

# 차단 사유 확인
if not response.candidates:
    print("Block reason:", response.prompt_feedback.block_reason)

차단된 카테고리는 prompt_feedback.safety_ratings 배열에서 확인 가능. 의료 콘텐츠가 자꾸 dangerous로 차단되면 시스템 프롬프트 첫 줄에 "교육 목적의 일반 의료 정보 안내" 명시하면 통과율 올라갑니다.

관련 글: Gemini API Python 연동 — 30분 안에 첫 봇 만들기

4. context_length 초과 — 200K 넘으면 가격 2배

증상: 입력 토큰이 200K를 넘으면 자동으로 long-context 가격(입력 100만 토큰당 2.50달러, 출력 15달러)이 적용돼요. 사전 알림 없이 청구되니 주의.

해결: token count API로 사전 확인.

# 입력 토큰 수 사전 확인
result = model.count_tokens(prompt)
print(f"Input tokens: {result.total_tokens}")

if result.total_tokens > 200_000:
    print("WARNING: long-context pricing will apply")
    # RAG 또는 요약으로 단축

한도 자체(2M 토큰) 초과: INVALID_ARGUMENT 에러. 시스템 프롬프트 + 히스토리 + 입력 + 도구 정의 합산이 2M 넘으면 발생. 히스토리 트리밍 또는 RAG 도입이 정답.

5. 스트리밍 중간 끊김 — finishReason: OTHER

스트리밍 응답이 중간에 끊기면서 마지막 청크가 안 오는 경우가 있어요. 원인 두 가지.

원인 1: 클라이언트 타임아웃 기본 60초. reasoning 긴 응답에서 끊김.

import google.generativeai as genai
from google.api_core import client_options

# 타임아웃 300초로 연장
client_opts = client_options.ClientOptions(api_endpoint=None)
genai.configure(
    api_key="YOUR_KEY",
    transport="rest",
)

# Per-request timeout
response = model.generate_content(
    prompt,
    request_options=dict(timeout=300),
    stream=True,
)

원인 2: finishReason이 STOP 아닌 OTHER, MAX_TOKENS, SAFETY로 종료됨. 스트리밍 마지막 chunk의 finishReason 반드시 검사.

for chunk in response:
    if chunk.candidates:
        cand = chunk.candidates[0]
        if cand.finish_reason and cand.finish_reason.name != "STOP":
            print(f"Abnormal finish: {cand.finish_reason.name}")

6. JSON 모드 응답 깨짐 — response_mime_type 미지정

Gemini 2.5에서 JSON 출력 강제하려면 response_mime_type="application/json" 옵션 명시 필요. 없으면 마크다운 코드 블록(```json) 감싸진 형태로 와서 파싱 실패.

response = model.generate_content(
    "주문 정보를 JSON으로 추출하세요. 입력: ...",
    generation_config=dict(
        response_mime_type="application/json",
        response_schema=dict(
            type="object",
            properties=dict(
                product=dict(type="string"),
                quantity=dict(type="integer"),
            ),
        ),
    ),
)

import json
data = json.loads(response.text)

response_schema까지 명시하면 스키마 강제 검증까지 들어가서 잘못된 필드 자동 거르기. 자동화 파이프라인엔 필수예요.

관련 글: Gemini API 함수 호출(function call) 실전 가이드

7. AI Studio 웹 UI 빨간 표시 — quota 또는 SAFETY

웹 UI에서 응답이 빨간 박스로 멈추면 두 가지 원인 중 하나예요.

원인 1: Pro 모델 일 50건 한도 초과. 화면 우상단 "Studio" 메뉴 → "API quota" 확인. 다음 날 태평양 시간 자정(한국 시간 오후 4시) 리셋.

원인 2: 안전 필터 차단. F12 개발자 도구 → Network 탭에서 generateContent 호출 클릭 → Response 탭에서 promptFeedback.blockReason 확인.

웹 UI 사용자는 보통 Flash 모델로 전환하면 즉시 해결. 좌측 모델 선택에서 "gemini-2.5-flash" 선택하면 한도가 15 RPM, 1,500 RPD로 30배 늘어나요.

지금 당장 적용할 액션 3가지

여기까지 7가지 오류 정리했으니 오늘부터 즉시 적용할 3가지 액션 정리할게요.

1. exponential backoff 라이브러리 도입 — tenacity 또는 google-api-core의 retry 데코레이터. 429·503 자동 재시도. 5분이면 추가 가능합니다.
2. 무료 티어 확인 → Flash 우선 사용 — Pro는 일 50건이라 자동화엔 부족. Flash 2.5로 동일한 품질 80% 확보 + 30배 한도.
3. safetySettings 명시 — BLOCK_ONLY_HIGH로 시작해서 차단 사유 발생할 때만 카테고리별 조정. 무해한 콘텐츠 차단율 70% 감소.

저도 이 3가지 적용 후 워크플로 안정성 95%까지 올렸어요. 에러 발생률이 시간당 6건 → 0.3건으로 떨어졌고요. 자동화 도입하셨으면 첫 주에 반드시 적용하세요.