사용자 가이드

오류 코드

LMU AI 오류 코드 참조: 401 / 403 / 404 / 429 / 5xx 상태 코드의 의미와 해결 방법, 배치 이미지 비즈니스 코드, 그리고 원시 오류 텍스트에서 해결 방법으로의 조회.

이 페이지는 개별 API 문서에 흩어져 있던 오류 코드를 하나의 치트 시트로 모았습니다. 먼저 HTTP 상태 코드로 큰 범주를 찾은 다음, 원시 오류 텍스트로 구체적인 해결 방법을 찾으세요.

문제 해결 전에 request ID를 기록하세요

응답 헤더의 request ID는 문제를 진단하는 데 가장 유용한 단일 정보입니다. 지원팀에 문의할 때는 request ID와 전체 오류 텍스트를 포함하세요 — 전체 API 키는 보내지 마세요.

HTTP 상태 코드

상태일반적인 원인조치 방법
400잘못된 요청 본문, 파라미터, 모델 ID 또는 모델 경로; 잘못된 이미지 형식 / 인코딩요청을 수정하세요 — 단순히 재시도하지 마세요; 계정을 바꾸거나 재시도해도 성공하지 않습니다
401API 키가 없거나, 잘못되었거나, 비활성화됨; Base URL이 프로토콜과 일치하지 않음; IDE를 재시작하지 않아 이전 설정이 여전히 적용됨키와 Base URL을 확인하고(API Protocols 참고), IDE를 재시작하세요; 자세한 내용은 Issue 3
402잔액 부족충전하거나 작업량을 줄이세요
403두 가지 가능성이 있으며, 둘 다 발생 가능: ① API 키의 그룹에 이미지 생성이 활성화되지 않음; ② 잔액, 구독, 청구 자격 또는 권한 부족먼저 계정 잔액과 구독 상태를 확인한 다음, 그룹에 해당 기능이 있는지 확인하세요; 둘 다 정상인데도 여전히 오류가 나면 지원팀에 문의하세요
404OpenAI 프로토콜 URL에 /v1 누락, Anthropic URL에 /v1 잘못 포함, Gemini가 /v1beta/models/...를 사용하지 않음; 또는 현재 그룹에서 지원하지 않는 엔드포인트API Protocols를 참고하여 Base URL과 전체 엔드포인트를 다시 확인하세요
413이미지-투-이미지 요청 본문이 너무 큼입력 이미지를 압축하세요
429① 일일 할당량 소진; ② 동시성, RPM 또는 업스트림 할당량 제한소진된 할당량은 Issue 2 참고; 속도 제한의 경우 지수 백오프로 물러나고 동시성과 RPM을 낮추세요
500내부 또는 용량 오류오류 코드와 request ID를 기록하고 제한된 횟수만 재시도하세요
502업스트림 인증, 권한 또는 서비스 일시 장애물러나서 재시도하고, 필요하면 지원팀에 문의하세요
503사용 가능한 업스트림 계정이 없거나 업스트림 과부하; 환경 변수가 키를 덮어쓰고 있을 수도 있음먼저 환경 변수를 확인하고(Issue 6 참고), 지연을 두고 트래픽을 낮추어 재시도하세요
504게이트웨이 또는 업스트림 타임아웃새롭고 독립적인 요청으로 다시 보내세요

무엇을 재시도하고, 무엇을 대신 수정해야 하는가

  • 재시도하지 말 것: 400, 401, 그리고 명시적인 잔액, 권한, 파라미터 또는 콘텐츠 정책 오류 — 요청 자체가 유효하지 않으며, 어떤 업스트림 계정이든 동일한 결과를 반환합니다. 먼저 요청을 수정해야 합니다.
  • 재시도해도 안전함: 429, 502, 503, 504, 그리고 네트워크 끊김, 연결 재설정, 읽기 타임아웃 — 모두 일시적 장애입니다. 반복 호출에 대한 요금 지불을 피하기 위해 지수 백오프로 제한된 횟수(2~3회 권장)만 재시도하세요; 429에서는 동시성과 RPM도 낮추세요.

이 분류는 이미지 API의 재시도 가이드에서 가져왔습니다 — Gemini Image · 재시도 가이드를 참고하세요.

각 API의 전체 오류 설명: Gemini Image, GPT Image, Grok Image, Gemini Batch Image.

비즈니스 오류 코드 (배치 이미지)

HTTP 상태 코드 외에도, Gemini Batch Image API는 비즈니스 오류 코드를 반환하며, 콘솔에 error code: BATCH_IMAGE_XXX와 request ID로 표시됩니다.

오류 코드HTTP의미조치 방법
BATCH_IMAGE_DISABLED404배치 이미지 생성이 전역적으로 비활성화됨오류 코드와 request ID를 관리자에게 보내세요
BATCH_IMAGE_GROUP_DISABLED403현재 키의 그룹이 배치 이미지를 허용하지 않거나 Gemini 그룹이 아님키를 변경하거나 관리자에게 그룹 권한 활성화를 요청하세요
BATCH_IMAGE_NO_ACCOUNT_AVAILABLE502현재 사용 가능한 배치 실행 리소스가 없음request ID를 저장하고 관리자에게 문의하세요
BATCH_IMAGE_SETTLEMENT_PRICING_MISSING400배치 모델에 청구 가격이 없음관리자에게 모델 가격 구성을 요청하세요
BATCH_IMAGE_INVALID_MODEL400모델이 제공되지 않음배치 모델 목록에서 모델을 사용하세요
BATCH_IMAGE_INVALID_ITEMS400유효하지 않은 항목, 해상도 또는 요청 필드요청 본문을 확인하세요; 현재는 1K만 지원됩니다
BATCH_IMAGE_DUPLICATE_CUSTOM_ID400중복된 custom_id배치 내에서 고유한지 확인하세요
BATCH_IMAGE_PROMPT_TOO_LONG400프롬프트가 너무 김프롬프트를 줄이세요
BATCH_IMAGE_TOO_MANY_OUTPUT_IMAGES400확장 후 이미지 수가 제한을 초과함항목 또는 output_count를 줄이세요
BATCH_IMAGE_INVALID_REFERENCE_IMAGE400유효하지 않은 참조 이미지 형식, 크기 또는 URIMIME, Base64, file_uri를 확인하세요
BATCH_IMAGE_INSUFFICIENT_BALANCE402청구를 예약하기에 잔액이 너무 낮음충전하거나 작업량을 줄이세요
BATCH_IMAGE_IDEMPOTENCY_CONFLICT409동일한 idempotency 키가 다른 요청 본문에 매핑됨새 Idempotency-Key를 사용하세요
BATCH_IMAGE_PROVIDER_SUBMIT_FAILED502업스트림 배치 작업 생성 실패request ID를 저장하고 제한된 횟수만 재시도하거나 관리자에게 문의하세요
BATCH_IMAGE_QUEUE_FAILED502비동기 작업 서비스가 일시적으로 사용 불가request ID를 저장하고 관리자에게 문의하세요
BATCH_IMAGE_NOT_READY409작업 완료 전에 다운로드를 시도함상태가 completed가 될 때까지 기다리세요
BATCH_IMAGE_OUTPUT_DELETED410출력이 이미 정리됨더 이상 다운로드할 수 없습니다; 작업을 다시 생성하세요
BATCH_IMAGE_ITEM_FAILED409지정된 작업 항목에 성공한 이미지가 없음item.error를 확인하세요
BATCH_IMAGE_DOWNLOAD_LIMITED429동시 다운로드가 너무 많음나중에 다시 시도하세요

원시 오류 텍스트로 조회하기

실제로 보이는 오류 텍스트를 아래 표와 대조하여 자세한 해결 방법으로 바로 이동하세요.

원시 오류 텍스트의미자세한 해결 방법
stream disconnected before completion스트림이 끊김, 보통 VPN / 프록시 / 시스템 프록시가 출구 IP를 교체하는 경우Issue 1
exceeded retry limit, last status: 429 Too Many Requests일일 할당량 소진Issue 2
401 Unauthorized: Incorrect API key provided요청이 LMU AI 릴레이가 아닌 공식 엔드포인트로 갔음Issue 3
running scripts is disabled on this system (Windows)PowerShell 실행 정책 제한Issue 4
CODEX is not recognized as a cmdlet (Windows)Node.js가 설치되지 않았거나 PATH가 손상됨Issue 5
503 No available accounts셸 환경 변수가 IDE에 구성된 키를 덮어씀Issue 6
400 Invalid signature in thinking block한 대화에서 그룹 간 모델 전환; thinking 서명을 검증할 수 없음Issue 7
400 Unknown parameter: 'tools[0].n'tools 파라미터가 이미지 엔드포인트로 잘못 전송됨Issue 8
No available accounts / model unavailable현재 그룹의 사용 가능 범위를 벗어난 모델을 호출함API Protocols → 문제 해결

Usage export API의 오류

Usage export API는 JWT 인증을 사용하므로, 위의 API 키 채널과 오류 의미가 다릅니다:

상태원인조치 방법
401JWT 만료refresh_token으로 갱신하거나 다시 로그인하세요
403권한 없는 접근 (예: 본인 소유가 아닌 api_key_id 조회)키가 현재 계정에 속하는지 확인하세요
400잘못된 파라미터 (예: 잘못된 start_date 형식)YYYY-MM-DD 형식과 timezone이 유효한지 확인하세요

여전히 막혔나요?

  • 단계별 실제 사례는 FAQ에 있습니다
  • Base URL / 엔드포인트 규칙은 API Protocols에 있습니다
  • 도난당한 키에 대한 보호는 Key Security에 있습니다
  • 지원팀에 문의할 때는 request ID와 전체 오류 텍스트를 포함하세요

마지막 업데이트:

FAQ

LMU AI API의 일반적인 오류 및 설정 문제 해결 방법 — 401 / 403 / 429 / 500, 토큰 과금, 모델 전환, Claude Code / Codex CLI 문제 해결.

키 보안

LMU AI API 키 IP 화이트리스트/블랙리스트 가이드: 어떤 IP가 키를 호출할 수 있는지 제한하여 유출된 키가 악용되는 것을 방지합니다. 단일 IP 및 CIDR 범위를 지원합니다.

이 페이지의 목차

HTTP 상태 코드비즈니스 오류 코드 (배치 이미지)원시 오류 텍스트로 조회하기Usage export API의 오류여전히 막혔나요?