Skip to content

错误处理 ​

所有 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 方案。
  • 令牌字符串有误(复制不完整、多余空格等)。
  • 令牌已被吊销,或令牌上的过期时间已到。

处理方式:

  1. 检查 Authorization: Bearer tsk_live_... 格式是否正确。
  2. 在 账户 → API 密钥 页面确认令牌状态为有效。
  3. 若令牌已吊销,创建新令牌。不要用旧的业务码 1004013000 判断这次调用:那个码不出现在 OpenAPI 认证失败里。

402 — 积分余额不足 ​

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

处理方式:

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

402 — 月度积分上限已超 ​

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

处理方式:

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

403 — 权限不足 ​

json
{
  "code": 403,
  "msg": "没有该操作权限",
  "data": null
}

可能原因:

  • 令牌缺少所需 Scope(例如只有 matting 时调用文生图)。此时 HTTP 状态是 403。
  • 查询的 taskId 属于其他用户。此时 HTTP 状态是 200,仍要看 body 里的 code。

处理方式:

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

429 — 频率限制 ​

json
{
  "code": 429,
  "msg": "请求过于频繁,请稍后重试",
  "data": null
}

响应头:

http
Retry-After: 45

处理方式:

  1. 读取响应头 Retry-After 的秒数。
  2. 等待该时长后重试。
  3. 不要立即重试,会持续触发 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:提交任务后返回的任务 ID
  • requestId:响应 data.requestId。提交时可通过请求体 requestId 或请求头 X-Request-Id 指定;省略时用服务端生成并返回的那个值
  • 请求时间:大致的 UTC 时间
  • 错误码:响应体中的 code 字段值
  • 接口路径:如 POST /image/text2image

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


错误码速查表 ​

codeHTTP 状态说明处理方式
0200成功(任务失败时 code 仍是 0,看 data.status)—
401401未登录。msg 为「账号未登录」检查/重建令牌,不要重试
403403 或 200没有该操作权限。Scope 不足时 HTTP 为 403;查询他人任务时 HTTP 为 200检查 Scope 或 taskId,不要重试
400200参数缺失或格式错误按 msg 修改请求
1004008000402积分余额不足充值后重试
1004013001402令牌月度积分上限已超提高上限或等待下月
1002041001200图像处理任务不存在检查 taskId
429429请求过于频繁,请稍后重试等待 Retry-After 后重试
500500 或 200系统异常,响应没有堆栈指数退避重试,持续失败联系支持

妙图设计 API Beta