> ## 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` | — | 批次内的单项失败（例如某条通道的数据库抖动）。只出现在 `results[].error` 中，从不作为 HTTP 状态。 | 是 |

<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"
  }
}
```

请参阅[无法服务的组合表](/zh/engines/capacity)。

`REGION_UNAVAILABLE` 是暂时性的：路径存在，但此刻没有可用资源。查询 [`GET /capacity`](/zh/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 所实现的异步任务协议的单项错误
  枚举中。它们是新增而非替换，`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`（无法匿名读取的 Naver 页面）会保留说明需要修改什么的消息。同一任务也会投递
`task.status === "FAILED"` 的 webhook。