오류 코드
연결 테스트 실패 또는 채팅 버블 오류 시 상세 보기를 눌러 본 페이지의 오류 코드（또는 문구 키워드）와 대조하세요.
상세에는 보통 다음이 있습니다:
- 오류 코드（영문 식별자, 예
invalidApiKey） - 오류 원인
- 시도할 수정
아래 「코드」는 App 오류 상세에 표시되는 이름을 기준으로 합니다.
빠른 대조표
| 오류 코드 | 사용자에게 보이는 요약 | 우선 처리 |
|---|---|---|
missingApiKey | API Key를 먼저 입력하세요 | 모델 연결에 키 입력 |
invalidApiKey | 키가 유효하지 않거나 만료 | 복사 완전성 확인; 콘솔에서 재발급 |
forbidden | 접근 거부 | 권한, 모델 개통 여부 |
regionForbidden | 지역에서 사용 불가 | 네트워크 / 프록시 / 국제 사이트 |
network | 네트워크 연결 실패 | 네트워크, Base URL, 방화벽 |
timeout | 요청 시간 초과 | 네트워크; 로컬 모델은 타임아웃 증가 |
modelNotFound | 모델이 없음 | 모델 ID 확인 |
modelRetired | 모델 오프라인 | 목록에서 현재 사용 가능 모델로 변경 |
rateLimit | 요청이 너무 잦음 | 대기 후 재시도 |
freeTierQuota | 무료 티어 요청 한도 | Please retry in … 대기; 빈도 낮추거나 유료 업그레이드 |
insufficientQuota | 한도 부족 | 충전 / 키 교체 |
spendingCapExceeded | 월 소비 상한 | 콘솔에서 spend cap 상향 |
providerReturnedError | 업스트림 오류 | 모델 변경 / 같은 벤더 :free 회피 / OpenRouter BYOK |
contextLengthExceeded | 컨텍스트 초과 | 기억 축소; 응답 토큰 None; 큰 컨텍스트 모델 |
anthropicMaxTokensRequired | Claude에 max_tokens 필요 | 모델 설정에서 「응답 토큰」켜기 |
badRequest | 파라미터 오류 | 파라미터와 호환 인터페이스 형식 확인 |
serverError | 서버 오류 | 잠시 후 재시도 |
requestFailed | 요청 실패 | 상세 원문 확인 |
contentPolicy | 안전 심사 미통과 | 재생성 / 모델 변경 / 다시 쓰기 |
emptyContent | 응답이 비어 있음 | 재시도; 사고 모델 필드 확인 |
modelAtCapacity | 모델 포화 | 대기 또는 모델 변경 |
productNotActivated | 제품 미개통 | 콘솔에서 모델 개통 |
visionUnsupported | 이미지 미지원 | 비전 모델로 바꾸거나 첨부 끄기 |
textOutputUnsupported | 텍스트 대화 미지원 | 텍스트 채팅 모델로 변경, TTS/이미지 전용 ID 금지 |
분류 상세
missingApiKey
- 현상: 키 없이 요청 불가.
- 처리: 설정 → 모델 연결 → API Key. 로컬 Ollama 등은 비어 있지 않은 자리 표시자（검증이 비어 있지 않음을 요구할 때）.
invalidApiKey
- 현상: 401류, 키 무효.
- 처리: 공백 없이 전체 복사; 국내/국제 사이트와 키 일치; 키 재발급.
forbidden / regionForbidden
- 현상: 403, 지역 제한.
- 처리: 모델 권한 확인; 프록시 또는 국제 Base URL.
network / timeout
- 현상: 연결 불가 또는 장시간 무응답.
- 처리:
- Base URL 확인（로컬은 폰의
localhost금지, PC LAN IP）. - PC 방화벽 포트 개방; 폰과 PC 같은 Wi‑Fi.
- 약한 망·느린 로컬 모델: 타임아웃 증가, 작은 모델.
- Base URL 확인（로컬은 폰의
modelNotFound
- 현상: 모델 ID 오류.
- 처리: 테스트 후 목록에서 다시 선택; 로컬은
ollama list/ LM Studio 표시명과 일치.
modelRetired
- 현상: HTTP 404,
no longer available to new users/use a newer model（예models/gemini-2.5-flash-lite）. - 구분: 벤더가 폐기했거나 신규에 개방하지 않음 — 오타가 아님.
- 처리: 모델 연결에서 최신 목록을 받아 온라인 Gemini（예
gemini-flash-latest）선택. Interactions API로 바꿀 필요 없음. 목록: Gemini models.
rateLimit
- 처리: 전송 빈도 낮추기; 잠시 후 재시도; 요금제 업그레이드.
freeTierQuota
- 현상: Gemini 등
HTTP 429+generate_content_free_tier_requests（자주 limit: 20）,Please retry in …s. - 구분: 무료 티어 분당/일일 요청 수 — 잔액 부족이나 프로젝트 월 spend cap이 아님.
- 처리: 안내 초 후 재시도; 빈도 낮추기; AI Studio 사용량; 더 높은 한도는 결제/유료. 설명: Gemini rate limits.
insufficientQuota / spendingCapExceeded
- 구분: 한도 소진 vs 프로젝트 월 소비 상한（후자는 대기만으로 보통 해결 안 됨）.
- 처리: 충전; 또는 콘솔에서 spend cap 조정（예 Google AI Studio Spend）.
providerReturnedError
- 현상: OpenRouter 등
HTTP 429: Provider returned error（:free에서 흔함）. - 처리: 잠시 후 재시도; 다른 벤더 한가한 모델; 또는 OpenRouter BYOK.
contextLengthExceeded
- 처리: 설정 → 모델 설정 → 기억 길이 축소; 「응답 토큰」을 None（해당 시）; 더 큰 컨텍스트 모델.
anthropicMaxTokensRequired
- 처리: Claude는 max_tokens 필수 → 모델 설정에서 「응답 토큰」켜기, None 금지.
badRequest
- 처리: temperature 등 확인; 제3자 호환 사이트가 진짜 OpenAI/Anthropic 형식인지.
serverError / requestFailed / modelAtCapacity
- 처리: 잠시 후 재시도; 엔드포인트·모델 변경; 지속 시 벤더에 상세 원문 첨부.
contentPolicy
- 처리: 재생성, 다시 쓰기, 심사가 느슨한 모델; 일부 NSFW 카드는 출력 차단이 잦음.
emptyContent
- 처리: 재시도; 일부 사고 모델은 reasoning만 반환 → 상세의 전체 필드 또는 모델 변경.
productNotActivated
- 처리: 클라우드 콘솔에서 해당 제품/모델 개통 후 현재 키 사용.
visionUnsupported
- 처리: 비전 지원 모델로; 또는 이미지 보내지 않기 / 이미지 인식 묘사로 순수 텍스트 묘사.
textOutputUnsupported
- 현상: HTTP 400,
response modalities와TEXT미지원（예models/gemini-2.5-flash-preview-tts는AUDIO만）. - 구분: TTS / 이미지 전용 모델을 채팅 테스트에 씀 — 키·샘플링 오타가 아님.
- 처리: 모델 연결에서 텍스트 채팅 모델（예
gemini-flash-latest）. 이름에tts·image가 있는 전용 ID 금지. 음성·이미지는 해당 기능에서 설정.
로컬 모델 전용
PC의 Ollama / LM Studio에 연결되지 않으면: 로컬 문제 해결.
App 테스트 / 채팅 오류（오류 코드 포함）: 매뉴얼 · 오류 코드.
스크린샷
