错误码与故障处理

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

{
  "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 出现未预期异常，已返回安全错误信息。

建议处理顺序

检查 HTTP 状态和 code

4xx 通常需要修改请求或成员配置；429 和 5xx 可能适合等待后重试。

检查 retryable

只有 retryable: true 或本页明确标记可重试的错误，才执行自动重试。

保存诊断编号

记录 request_id 或响应头中的 X-Linggan-Request-Id，不要记录 Public API Key。

限制重试次数

使用指数退避和随机抖动，通常最多自动重试 2 至 4 次。

开始使用

接入准备

业务调用

排查问题

认证与成员配置

图片上传

任务与重复提交

AI 与上游服务

建议处理顺序

​认证与成员配置

​图片上传

​任务与重复提交

​AI 与上游服务

​建议处理顺序

认证与成员配置

图片上传

任务与重复提交

AI 与上游服务

建议处理顺序