API 에러 대응 가이드

자주 발생하는 에러와 해결법

429 Too Many Requests (레이트 리밋)

원인: 무료 티어 호출 한도 초과 증상: 제갈량이 "billing error" 메시지 출력 해결:

• 1~2분 기다린 후 재시도
• 레이트 리밋이 자주 걸리면 유료 전환 고려
• 또는 Claude 백업 모델 활성화 ($5 충전)

Gemini 무료 레이트 리밋:

• 분당 15회 (RPM)
• 일 1,500회 (RPD)
• 분당 100만 토큰 (TPM)

401 Unauthorized (인증 실패)

원인: API 키가 잘못되었거나 만료 증상: "invalid API key" 또는 "unauthorized" 해결:

• docker-compose.yml에서 키 확인
• 키 재발급 후 교체
• 컨테이너 재시작: docker-compose down && docker-compose up -d

400 Bad Request (잘못된 요청)

원인: 요청 형식 오류, 모델명 오타, 파라미터 누락 증상: "invalid request" 또는 "bad request" 해결:

• 모델명 정확한지 확인 (예: claude-sonnet-4-6, gemini-2.5-flash)
• 요청 JSON 형식 검증