主题
错误处理
所有 API 响应均使用统一的 CommonResult 包装体:
json
{
"code": <整数>,
"msg": "<消息字符串或 null>",
"data": <业务数据或 null>
}code: 0表示成功。code非 0 表示错误,具体含义见本文档的错误码表。
HTTP 状态码说明
| HTTP 状态 | 含义 | 处理建议 |
|---|---|---|
200 | 传输成功,业务结果看 body 里的 code | 先读 code |
401 | 未提供令牌、令牌无效、已吊销或已过期 | 检查令牌,不要重试 |
402 | 积分不足或月度上限已达 | 充值或调整上限后重试 |
403 | 令牌缺少该接口的 Scope | 检查 Scope,不要重试 |
429 | 超过该令牌的每分钟次数上限 | 等待 Retry-After 秒后重试 |
HTTP 200 不代表业务成功,必须检查
code。参数错误、任务不存在、查询他人任务,以及多数服务端异常,HTTP 状态仍是 200,错误在code里。认证过滤器抛出的 401/403、计费的 402、频率限制的 429 才会设置对应的 HTTP 状态。服务端异常的msg是「系统异常」,响应里没有堆栈。
业务错误码详细说明
401 — 令牌无效
json
{
"code": 401,
"msg": "账号未登录",
"data": null
}可能原因:
- 没有
Authorization头,或不是Bearer方案。 - 令牌字符串有误(复制不完整、多余空格等)。
- 令牌已被吊销,或令牌上的过期时间已到。
处理方式:
- 检查
Authorization: Bearer tsk_live_...格式是否正确。 - 在 账户 → API 密钥 页面确认令牌状态为有效。
- 若令牌已吊销,创建新令牌。不要用旧的业务码
1004013000判断这次调用:那个码不出现在 OpenAPI 认证失败里。
402 — 积分余额不足
json
{
"code": 1004008000,
"msg": "用户积分余额不足",
"data": null
}处理方式:
- 调用
GET /account/balance确认available余额。 - 在妙图产品内充值积分。
- 余额补充后重新发起请求。
402 — 月度积分上限已超
json
{
"code": 1004013001,
"msg": "API Token 月度积分上限已超过",
"data": null
}处理方式:
- 在 账户 → API 密钥 页面找到该令牌,提高月度积分上限。
- 或等待下个自然月自动重置。
403 — 权限不足
json
{
"code": 403,
"msg": "没有该操作权限",
"data": null
}可能原因:
- 令牌缺少所需 Scope(例如只有
matting时调用文生图)。此时 HTTP 状态是403。 - 查询的
taskId属于其他用户。此时 HTTP 状态是200,仍要看 body 里的code。
处理方式:
- 检查令牌 Scope 是否包含当前接口所需的权限。
- 参考 Scope 说明 重新分配权限后创建新令牌。
- 不要跨账户查询他人任务。
taskId不存在时不是 403,见下文。
429 — 频率限制
json
{
"code": 429,
"msg": "请求过于频繁,请稍后重试",
"data": null
}响应头:
http
Retry-After: 45处理方式:
- 读取响应头
Retry-After的秒数。 - 等待该时长后重试。
- 不要立即重试,会持续触发 429。
任务失败(status: 2)
任务状态为 2(FAILURE)时,HTTP 状态码仍为 200(成功返回了任务信息),但任务本身处理失败:
json
{
"code": 0,
"msg": "",
"data": {
"taskId": "img-abc123",
"status": 2,
"resultType": "image",
"resultMetadata": "{\"errorMessage\":\"图片地址无法下载\"}",
"imageUrls": [],
"imagePreviewUrls": []
}
}resultMetadata 是字符串。失败时它常常是一段 JSON,说明在 errorMessage 里;也可能是空的。这段文字不是稳定错误码,原文可能是内部处理信息,不要按其中的字面值写分支。能判断是输入问题(例如图片 URL 无法下载)时,改输入后重新提交。判断不了就记下 taskId 和 requestId 联系支持。
400 — 请求参数不正确
校验失败时 HTTP 状态仍是 200,例如缺少必填字段:
json
{
"code": 400,
"msg": "请求参数不正确:positive 不能为空",
"data": null
}请求体不是 JSON,或根本没有请求体时,code 也是 400,msg 为「请求参数格式错误」或「请求体缺失」。按 msg 改请求,不要当服务端故障重试。
任务不存在
GET /tasks/{taskId} 查不到任务时,HTTP 状态是 200:
json
{
"code": 1002041001,
"msg": "图像处理任务不存在",
"data": null
}这和「任务属于别人」(code 403)不是同一种错误。
请求 ID 与支持工单
联系支持时,请提供以下信息以便快速定位问题:
taskId:提交任务后返回的任务 IDrequestId:响应data.requestId。提交时可通过请求体requestId或请求头X-Request-Id指定;省略时用服务端生成并返回的那个值- 请求时间:大致的 UTC 时间
- 错误码:响应体中的
code字段值 - 接口路径:如
POST /image/text2image
建议在每次调用时生成唯一 requestId(使用 UUID v4),并在日志中记录,方便事后追溯。
错误码速查表
| code | HTTP 状态 | 说明 | 处理方式 |
|---|---|---|---|
0 | 200 | 成功(任务失败时 code 仍是 0,看 data.status) | — |
401 | 401 | 未登录。msg 为「账号未登录」 | 检查/重建令牌,不要重试 |
403 | 403 或 200 | 没有该操作权限。Scope 不足时 HTTP 为 403;查询他人任务时 HTTP 为 200 | 检查 Scope 或 taskId,不要重试 |
400 | 200 | 参数缺失或格式错误 | 按 msg 修改请求 |
1004008000 | 402 | 积分余额不足 | 充值后重试 |
1004013001 | 402 | 令牌月度积分上限已超 | 提高上限或等待下月 |
1002041001 | 200 | 图像处理任务不存在 | 检查 taskId |
429 | 429 | 请求过于频繁,请稍后重试 | 等待 Retry-After 后重试 |
500 | 500 或 200 | 系统异常,响应没有堆栈 | 指数退避重试,持续失败联系支持 |
