# 오류 코드

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

URL: https://docs.lmuai.com/ko/docs/guide/errors



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

<Callout type="info" title="문제 해결 전에 request ID를 기록하세요">
  응답 헤더의 request ID는 문제를 진단하는 데 가장 유용한 단일 정보입니다. 지원팀에 문의할 때는 request ID와 전체 오류 텍스트를 포함하세요 — **전체 API 키는 보내지 마세요**.
</Callout>

***

## HTTP 상태 코드 [#http-상태-코드]

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

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

  이 분류는 이미지 API의 재시도 가이드에서 가져왔습니다 — [Gemini Image · 재시도 가이드](/ko/docs/api/gemini-image#retry-recommendations)를 참고하세요.
</Callout>

각 API의 전체 오류 설명: [Gemini Image](/ko/docs/api/gemini-image), [GPT Image](/ko/docs/api/gpt-image), [Grok Image](/ko/docs/api/grok-image), [Gemini Batch Image](/ko/docs/api/gemini-image-batch).

***

## 비즈니스 오류 코드 (배치 이미지) [#비즈니스-오류-코드-배치-이미지]

HTTP 상태 코드 외에도, [Gemini Batch Image API](/ko/docs/api/gemini-image-batch)는 비즈니스 오류 코드를 반환하며, 콘솔에 `error code: BATCH_IMAGE_XXX`와 request ID로 표시됩니다.

| 오류 코드                                    | HTTP | 의미                                       | 조치 방법                                       |
| ---------------------------------------- | ---: | ---------------------------------------- | ------------------------------------------- |
| `BATCH_IMAGE_DISABLED`                   |  404 | 배치 이미지 생성이 전역적으로 비활성화됨                   | 오류 코드와 request ID를 관리자에게 보내세요               |
| `BATCH_IMAGE_GROUP_DISABLED`             |  403 | 현재 키의 그룹이 배치 이미지를 허용하지 않거나 Gemini 그룹이 아님 | 키를 변경하거나 관리자에게 그룹 권한 활성화를 요청하세요             |
| `BATCH_IMAGE_NO_ACCOUNT_AVAILABLE`       |  502 | 현재 사용 가능한 배치 실행 리소스가 없음                  | request ID를 저장하고 관리자에게 문의하세요                |
| `BATCH_IMAGE_SETTLEMENT_PRICING_MISSING` |  400 | 배치 모델에 청구 가격이 없음                         | 관리자에게 모델 가격 구성을 요청하세요                       |
| `BATCH_IMAGE_INVALID_MODEL`              |  400 | 모델이 제공되지 않음                              | 배치 모델 목록에서 모델을 사용하세요                        |
| `BATCH_IMAGE_INVALID_ITEMS`              |  400 | 유효하지 않은 항목, 해상도 또는 요청 필드                 | 요청 본문을 확인하세요; 현재는 1K만 지원됩니다                 |
| `BATCH_IMAGE_DUPLICATE_CUSTOM_ID`        |  400 | 중복된 `custom_id`                          | 배치 내에서 고유한지 확인하세요                           |
| `BATCH_IMAGE_PROMPT_TOO_LONG`            |  400 | 프롬프트가 너무 김                               | 프롬프트를 줄이세요                                  |
| `BATCH_IMAGE_TOO_MANY_OUTPUT_IMAGES`     |  400 | 확장 후 이미지 수가 제한을 초과함                      | 항목 또는 output\_count를 줄이세요                   |
| `BATCH_IMAGE_INVALID_REFERENCE_IMAGE`    |  400 | 유효하지 않은 참조 이미지 형식, 크기 또는 URI             | MIME, Base64, file\_uri를 확인하세요              |
| `BATCH_IMAGE_INSUFFICIENT_BALANCE`       |  402 | 청구를 예약하기에 잔액이 너무 낮음                      | 충전하거나 작업량을 줄이세요                             |
| `BATCH_IMAGE_IDEMPOTENCY_CONFLICT`       |  409 | 동일한 idempotency 키가 다른 요청 본문에 매핑됨         | 새 Idempotency-Key를 사용하세요                    |
| `BATCH_IMAGE_PROVIDER_SUBMIT_FAILED`     |  502 | 업스트림 배치 작업 생성 실패                         | request ID를 저장하고 제한된 횟수만 재시도하거나 관리자에게 문의하세요 |
| `BATCH_IMAGE_QUEUE_FAILED`               |  502 | 비동기 작업 서비스가 일시적으로 사용 불가                  | request ID를 저장하고 관리자에게 문의하세요                |
| `BATCH_IMAGE_NOT_READY`                  |  409 | 작업 완료 전에 다운로드를 시도함                       | 상태가 completed가 될 때까지 기다리세요                  |
| `BATCH_IMAGE_OUTPUT_DELETED`             |  410 | 출력이 이미 정리됨                               | 더 이상 다운로드할 수 없습니다; 작업을 다시 생성하세요             |
| `BATCH_IMAGE_ITEM_FAILED`                |  409 | 지정된 작업 항목에 성공한 이미지가 없음                   | item.error를 확인하세요                           |
| `BATCH_IMAGE_DOWNLOAD_LIMITED`           |  429 | 동시 다운로드가 너무 많음                           | 나중에 다시 시도하세요                                |

***

## 원시 오류 텍스트로 조회하기 [#원시-오류-텍스트로-조회하기]

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

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

***

## Usage export API의 오류 [#usage-export-api의-오류]

[Usage export API](/ko/docs/api/usage-export)는 JWT 인증을 사용하므로, 위의 API 키 채널과 오류 의미가 다릅니다:

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

***

## 여전히 막혔나요? [#여전히-막혔나요]

* 단계별 실제 사례는 [FAQ](/ko/docs/guide/faq)에 있습니다
* Base URL / 엔드포인트 규칙은 [API Protocols](/ko/docs/guide/api-protocols)에 있습니다
* 도난당한 키에 대한 보호는 [Key Security](/ko/docs/guide/key-security)에 있습니다
* 지원팀에 문의할 때는 **request ID**와 전체 오류 텍스트를 포함하세요