> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류

> 오류 봉투, API가 반환하는 모든 코드, 재시도할 가치가 있는 경우.

실패는 하나의 봉투를 공유합니다.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

`code`는 안정적이며 분기 조건으로 써도 안전합니다. `message`는 사람이 읽는 용도이고 바뀔 수
있습니다. `details`는 문제 필드를 특정할 수 있을 때 포함됩니다.

## 코드

| 코드 | 상태 | 의미 | 재시도 |
| - | - | - | - |
| `MISSING_API_KEY` | 401 | Bearer 토큰이 없거나 틀렸습니다. | 아니요, 키를 고치세요 |
| `VALIDATION_ERROR` | 400 | 본문 형식 오류, 알 수 없는 `taskType`, 또는 `payload.prompt`와 `payload.query`가 모두 없음. | 아니요, 요청을 고치세요 |
| `REGION_UNSUPPORTED` | 422 | 이 엔진은 요청한 `country`를 절대 서빙할 수 없습니다. | 아니요, 다른 엔진이나 지역을 고르세요 |
| `REGION_UNAVAILABLE` | 422 | 지금은 이 엔진에서 요청한 `country`에 쓸 용량이 없습니다. | 나중에, 용량이 돌아온 뒤 |
| `RESOURCE_ALREADY_EXISTS` | 409 | 단건 엔드포인트에서 `idempotencyKey`가 중복됐습니다. | 아니요, 태스크가 이미 있습니다 |
| `PAYLOAD_TOO_LARGE` | 413 | 배치 본문이 8 MB를 넘습니다. | 아니요, 더 작게 나눠 보내세요 |
| `RESOURCE_NOT_FOUND` | 404 | 알 수 없는 태스크 id이거나, 24시간 공개 폴링 기간이 지났습니다. | 아니요 |
| `ENQUEUE_ERROR` | — | 배치 안의 항목별 실패(예: 한 레인의 일시적 DB 문제). HTTP 상태가 아니라 `results[].error`에만 나타납니다. | 예 |

<Note>
  `400`은 파싱하거나 이해할 수 없는 요청에 씁니다. `422`는 형식은 완벽하지만 요청한 지역에서 서빙할
  수 없는 요청에만 씁니다. 상태 코드보다 `error.code`로 분기하는 편이 더 오래 유지됩니다.
</Note>

## 지역 거부

두 지역 코드는 모두 태스크를 큐에 넣기 **전에** 결정됩니다. 태스크가 재시도 예산을 다 쓰고
증상만 보이는 오류로 실패하는 것을 지켜볼 필요 없이 즉시 알 수 있습니다.

`REGION_UNSUPPORTED`는 영구적입니다. 해당 엔진은 요청한 국가를 서빙할 수 없습니다.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

[서빙할 수 없는 조합 표](/ko/engines/capacity)를 참고하세요.

`REGION_UNAVAILABLE`는 일시적입니다. 경로는 있지만 지금은 서빙할 수 있는 것이 없습니다.
[`GET /capacity`](/ko/api-reference/capacity)로 지역별로 현재 서빙 가능한 범위를 확인하세요.

## 배치 실패는 항목별입니다

형식이 올바른 배치는 안의 태스크가 모두 실패해도 항상 `200`을 반환합니다. HTTP 상태는 *요청*을,
`results[].success`는 각 *태스크*를 설명합니다.

```json theme={null}
{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}
```

요청 전체가 잘못된 경우(JSON이 아님, 배열이 아님, 비어 있음, 500개 초과, 8 MB 초과, 인증 실패)에만
배치 자체가 4xx를 반환합니다.

<Note>
  배치 항목은 `REGION_UNAVAILABLE` 또는 `ENQUEUE_ERROR`로 실패할 수 있는데, 둘 다 이 API가 구현하는
  비동기 태스크 계약의 항목별 오류 enum에는 없습니다. 둘은 대체가 아니라 추가이며,
  `VALIDATION_ERROR`와 `RESOURCE_ALREADY_EXISTS`는 그대로입니다.
</Note>

## 태스크 수준 실패

큐에 들어간 *뒤에* 실패한 태스크는 HTTP 오류를 전혀 만들지 않습니다. 종료 상태로 알게 됩니다.

```json theme={null}
{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}
```

형태 차이에 주의하세요. 이 최상위 `error`는 요청 수준 오류가 쓰는 `{code, message, timestamp}`
객체가 아니라 **문자열**입니다. 코드로 시작하고 그 코드마다 정해진 문장이
뒤따르므로 코드로 분기하세요. `ENGINE_TIMEOUT`, `ENGINE_NO_RESULT`, `ENGINE_FAILED`가 있고, 제시간에 처리 용량이
나지 않으면 `NO_IP_AVAILABLE`이나 `NO_ACCOUNT_AVAILABLE`입니다(보통 나중에 다시 시도하면 됩니다). `BAD_PAYLOAD`와
`PAGE_UNAVAILABLE`(익명으로 읽을 수 없는 네이버 페이지)은 무엇을 바꿔야 하는지 알려주는 메시지를 그대로 둡니다.
같은 태스크는 `task.status === "FAILED"`인 webhook도 전달합니다.