错误处理

所有 API 响应均使用统一的 CommonResult 包装体：

{
  "code": <整数>,
  "msg": "<消息字符串或 null>",
  "data": <业务数据或 null>
}

• code: 0 表示成功。
• code 非 0 表示错误，具体含义见本文档的错误码表。

---

HTTP 状态码说明

HTTP 状态	含义	处理建议
200	请求处理成功（需进一步检查 code）	读取 code 判断业务结果
401	令牌无效、已吊销、或未提供	检查令牌，不要重试
402	积分不足或月度上限已达	充值/调整上限后重试
403	无权访问（Scope 不足，或跨用户访问任务）	检查令牌 Scope，不要重试
429	触发频率限制	等待 Retry-After 秒后重试
5xx	服务端内部错误	指数退避后重试，仍失败则联系支持

注意：HTTP 200 不代表业务成功，必须检查响应体中的 code 字段。

---

业务错误码详细说明

401 — 令牌无效

{
  "code": 1004013000,
  "msg": "API Token 不存在",
  "data": null
}

可能原因：

• 令牌字符串有误（复制不完整、多余空格等）。
• 令牌已被手动吊销。
• 令牌属于其他账户。

处理方式：

1. 检查 Authorization: Bearer tsk_live_... 格式是否正确。
2. 在 账户 → API 密钥 页面确认令牌状态为有效。
3. 若令牌已吊销，创建新令牌。

---

402 — 积分余额不足

{
  "code": 1004008000,
  "msg": "用户积分余额不足",
  "data": null
}

处理方式：

1. 调用 GET /account/balance 确认 available 余额。
2. 在妙图产品内充值积分。
3. 余额补充后重新发起请求。

---

402 — 月度积分上限已超

{
  "code": 1004013001,
  "msg": "API Token 月度积分上限已超过",
  "data": null
}

处理方式：

1. 在 账户 → API 密钥 页面找到该令牌，提高月度积分上限。
2. 或等待下个自然月自动重置。

---

403 — 权限不足

无标准业务错误码，HTTP 状态码为 403。

可能原因：

• 令牌缺少所需 Scope（例如用仅有 matting Scope 的令牌调用 text2image 接口）。
• 查询的 taskId 不属于当前令牌所属用户。

处理方式：

1. 检查令牌 Scope 是否包含当前接口所需的权限。
2. 参考 Scope 说明 重新分配权限后创建新令牌。
3. 不要跨账户查询他人任务。

---

429 — 频率限制

{
  "code": 429,
  "msg": "Too Many Requests",
  "data": null
}

响应头：

Retry-After: 45

处理方式：

1. 读取响应头 Retry-After 的秒数。
2. 等待该时长后重试。
3. 不要立即重试，会持续触发 429。

---

任务失败（status: 2）

任务状态为 2（FAILURE）时，HTTP 状态码仍为 200（成功返回了任务信息），但任务本身处理失败：

{
  "code": 0,
  "msg": null,
  "data": {
    "taskId": "img-abc123",
    "status": 2,
    "resultMetadata": "图像分辨率过低，无法处理",
    "imageUrls": [],
    "imagePreviewUrls": []
  }
}

处理方式：

1. 查看 resultMetadata 字段中的失败原因。
2. 根据原因调整输入参数后重新提交任务。
3. 若失败原因不明，记录 taskId 和 requestId 后联系支持。

---

请求 ID 与支持工单

联系支持时，请提供以下信息以便快速定位问题：

• taskId：提交任务后返回的任务 ID
• requestId：提交时传入的 requestId 或 X-Request-Id 头的值
• 请求时间：大致的 UTC 时间
• 错误码：响应体中的 code 字段值
• 接口路径：如 POST /image/text2image

建议在每次调用时生成唯一 requestId（使用 UUID v4），并在日志中记录，方便事后追溯。

---

错误码速查表

code	HTTP 状态	说明	处理方式
0	200	成功	—
1004013000	401	API Token 不存在或已吊销	检查/重建令牌
1004008000	402	积分余额不足	充值后重试
1004013001	402	令牌月度积分上限已超	提高上限或等待下月
—	403	Scope 不足或跨用户访问	检查令牌权限
—	429	频率限制	等待 Retry-After 后重试
—	5xx	服务端错误	指数退避重试，持续失败联系支持