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

# 错误码与故障处理

> 公开错误码、HTTP 状态、重试条件和排查步骤

错误响应统一采用以下结构。`error.code` 是 HTTP 状态码，`error.type` 是稳定错误类别；具体字段原因放在 `param` 和 `details` 中，不为每个参数组合创建新枚举：

```json theme={null}
{
  "error": {
    "code": 503,
    "type": "service_unavailable_error",
    "message": "服务暂时不可用，请稍后重试",
    "retryable": true
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}
```

客户端应同时依据 HTTP 状态、`error.type` 和 `error.retryable` 判断是否重试。`request_id` 用于联系平台排查问题。

## 认证与成员配置

| HTTP | `error.type`                | 是否重试 | 说明                            |
| ---: | --------------------------- | ---- | ----------------------------- |
|  401 | `authentication_error`      | 否    | 缺少、错误、过期或已删除的 Public API Key。 |
|  403 | `permission_error`          | 否    | 成员或组织已停用。                     |
|  409 | `conflict_error`            | 否    | 成员未分配上游密钥，或已分配密钥暂时不可用。        |
|  503 | `service_unavailable_error` | 稍后   | 当前环境认证能力不可用。                  |

## 图片上传

| HTTP | 错误码                         | 是否重试 | 说明                          |
| ---: | --------------------------- | ---- | --------------------------- |
|  400 | `invalid_request_error`     | 否    | 表单中缺少 `file`，或图片格式不支持、文件损坏。 |
|  413 | `invalid_request_error`     | 否    | 图片超过 30 MB。                 |
|  503 | `service_unavailable_error` | 稍后   | 图片存储未配置或不可用。                |
|  405 | `request_error`             | 否    | 使用了错误的 HTTP 方法。             |

## 任务与重复提交

| HTTP | 错误码                | 是否重试 | 说明                        |
| ---: | ------------------ | ---- | ------------------------- |
|  404 | `not_found_error`  | 否    | 任务不存在，或不属于当前成员/密钥。        |
|  409 | `conflict_error`   | 是    | 相同生成请求仍在处理中，等待后查询既有任务或重试。 |
|  429 | `rate_limit_error` | 是    | 请求过于频繁，遵循 `Retry-After`。  |

## AI 与上游服务

| HTTP | 错误码                         | 是否重试 | 说明                        |
| ---: | --------------------------- | ---- | ------------------------- |
|  502 | `upstream_error`            | 是    | 无法连接上游服务、返回格式异常或生成失败。     |
|  503 | `service_unavailable_error` | 是    | Worker 出现未预期异常，已返回安全错误信息。 |

## 建议处理顺序

<Steps>
  <Step title="检查 HTTP 状态和 code">
    `4xx` 通常需要修改请求或成员配置；`429` 和 `5xx` 可能适合等待后重试。
  </Step>

  <Step title="检查 retryable">
    只有 `retryable: true` 或本页明确标记可重试的错误，才执行自动重试。
  </Step>

  <Step title="保存诊断编号">
    记录 `request_id` 或响应头中的 `X-Linggan-Request-Id`，不要记录 Public API Key。
  </Step>

  <Step title="限制重试次数">
    使用指数退避和随机抖动，通常最多自动重试 2 至 4 次。
  </Step>
</Steps>