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

# 错误码参考

## HTTP 状态码

| 状态码   | 描述      | 常见原因                       |
| ----- | ------- | -------------------------- |
| `200` | 成功      | 请求处理成功                     |
| `400` | 请求格式错误  | JSON 格式错误、Content-Type 不正确 |
| `401` | 未授权     | API Key 无效、过期或缺失           |
| `402` | 余额不足    | 账户余额不足，请充值后重试              |
| `404` | 未找到     | 任务 ID 不存在                  |
| `422` | 参数校验失败  | 缺少必填字段、参数值不合法、模型不存在        |
| `429` | 请求频率超限  | 超出速率限制，请稍后重试               |
| `500` | 服务器内部错误 | 服务端未知错误，请稍后重试              |
| `503` | 服务暂不可用  | 当前模型无可用渠道或上游服务异常，请稍后重试     |

## 错误响应格式

所有错误响应遵循以下格式：

```json theme={null}
{
  "error": {
    "message": "错误描述",
    "type": "error_type"
  }
}
```

任务失败时，任务查询响应中的 `error` 字段包含额外的 `code` 字段：

```json theme={null}
{
  "error": {
    "code": "specific_error_code",
    "message": "错误描述",
    "type": "task_error"
  }
}
```

## 错误类型

| 错误类型                        | 对应状态码    | 描述               |
| --------------------------- | -------- | ---------------- |
| `invalid_request_error`     | 400, 422 | 请求格式错误或参数校验失败    |
| `authentication_error`      | 401      | API Key 无效、过期或缺失 |
| `insufficient_quota`        | 402      | 账户余额不足           |
| `not_found`                 | 404      | 请求的资源不存在         |
| `rate_limit_error`          | 429      | 请求频率超限           |
| `server_error`              | 500      | 服务器内部错误          |
| `service_unavailable_error` | 422      | 模型暂时不可用（无可用渠道）   |

## 提交阶段错误码

提交任务时，如果参数校验通过但渠道匹配失败，会返回 `422` 状态码，`error.code` 字段包含以下错误码：

| 错误码                               | 描述                | 建议操作                                                           |
| --------------------------------- | ----------------- | -------------------------------------------------------------- |
| `unsupported_advanced_options`    | 请求中的高级参数当前无可用渠道支持 | 参考响应中的 `unsupported_advanced_options` 字段（每项含参数名与默认值），移除这些参数后重试 |
| `param_constraints_unsatisfiable` | 参数值超出当前可用渠道支持的范围  | 检查参数值是否在文档标注的可选值范围内                                            |
| `no_compatible_channel`           | 该模型暂时无可用渠道        | 稍后重试                                                           |
| `invalid_file_type`               | 媒体文件的实际内容与期望类型不符  | 检查文件是否损坏或扩展名与内容不一致                                             |

### 文件类型不匹配（invalid\_file\_type）

提交任务时，系统会对请求中的媒体文件 URL（`image_url`、`audio_url`、`video_url` 等）进行内容检测。如果文件的实际格式与字段期望的类型不一致（例如 `audio_url` 指向的文件实际是压缩包），会返回 `422` 状态码和 `invalid_file_type` 错误码。

响应中包含以下额外字段，便于前端定位问题：

| 字段              | 描述                                    |
| --------------- | ------------------------------------- |
| `field`         | 触发校验失败的参数名（如 `audio_url`）             |
| `detected_type` | 检测到的实际 MIME 类型（如 `application/x-tar`） |
| `expected_type` | 期望的媒体类别（`image` / `audio` / `video`）  |

示例响应：

```json theme={null}
{
  "error": {
    "message": "The file '002543212992.mp3' is detected as tar 归档文件 (application/x-tar), not a valid audio file. Please verify the file content matches the expected format.",
    "type": "invalid_request_error",
    "code": "invalid_file_type",
    "field": "audio_url",
    "detected_type": "application/x-tar",
    "expected_type": "audio"
  }
}
```

<Note>
  文件类型检测基于文件头的 magic bytes，不依赖文件扩展名或 HTTP Content-Type header。如果文件本身格式正确但无法识别（如不常见的编码格式），系统会静默放行，不会阻断请求。
</Note>

### 高级参数暂不支持（unsupported\_advanced\_options）

部分参数为**高级参数**，不是所有渠道都支持。当请求中包含的高级参数在当前模型的所有可用渠道上都不被支持时，会返回 `422` 状态码和 `unsupported_advanced_options` 错误码。

响应中包含以下结构化字段，便于程序解析：

| 字段                             | 描述                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `model`                        | 触发该错误的模型 ID                                                                      |
| `unsupported_advanced_options` | 不支持的高级参数列表，每一项包含 `param`（参数名）和 `default_value`（该参数在请求 Schema 中的默认值，移除参数后系统按此值处理） |

示例响应：

```json theme={null}
{
  "error": {
    "message": "The advanced options [enhance_prompt, seed] are not supported by any available channel for model 'veo-3.1'. Remove the unsupported options to proceed.",
    "type": "invalid_request_error",
    "code": "unsupported_advanced_options",
    "model": "veo-3.1",
    "unsupported_advanced_options": [
      {"param": "enhance_prompt", "default_value": false},
      {"param": "seed", "default_value": null}
    ]
  }
}
```

<Tip>
  * 高级参数在各模型的 API 文档中以 `x-advanced` 标记。移除不支持的高级参数不影响核心功能，生成结果仍然正常。
  * `default_value` 来自请求 Schema 的字段默认值（`null` 表示该参数本就可选、不传时系统不会附加任何值）。
</Tip>

## 任务相关错误码

查询任务状态时，状态为 `failed` 的任务会在 `error.code` 字段中包含以下错误码：

| 错误码                        | 描述                | 建议操作           |
| -------------------------- | ----------------- | -------------- |
| `task_failed`              | 任务执行失败（通用）        | 重新发起请求         |
| `content_policy_violation` | 输入内容违反内容策略        | 修改提示词后重试       |
| `invalid_image_url`        | 提供的图像/视频 URL 无法访问 | 检查 URL 是否公开可访问 |
| `file_too_large`           | 上传的文件超出大小限制       | 减小文件大小         |
| `unsupported_format`       | 不支持的文件格式          | 使用支持的格式        |

## 速率限制

* 速率限制按 API Key 应用
* 被限速时返回 `429` 状态码，请等待后重试
* 如需更高速率限制，请联系客服

## 最佳实践

1. **始终检查 HTTP 状态码** 再解析响应体
2. **实现指数退避** 对 `429` 和 `5xx` 错误进行重试
3. **记录错误响应** 用于调试和排查
4. **合理轮询任务状态** 建议间隔 3-5 秒，避免过于频繁
5. **优雅处理异步任务** 生成任务耗时因模型而异，请参考各模型文档中的预计时间