错误码

开放 API 的错误统一用秒做自己的字符串错误码表示：HTTP 状态码说明大类，error.code 说明具体原因。

错误格式

接口出错时返回非 2xx 状态码和统一的错误体。request_id 与响应头 X-Request-Id 相同，联系我们排查问题时请提供。文本模型兼容接口的错误体结构见文本模型。

错误返回示例

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: req_xaw1zhb0bh6app6dnbxtq7yj

{
  "error": {
    "code": "invalid_params",
    "message": "画面描述不能为空",
    "request_id": "req_xaw1zhb0bh6app6dnbxtq7yj",
    "details": [
      {
        "field": "prompt",
        "message": "画面描述不能为空"
      },
      {
        "field": "ratio",
        "message": "画面比例不在可选范围内（可选：1:1、3:4、4:3、9:16、16:9）"
      }
    ]
  }
}

字段	类型	说明
`error.code`	string	错误码，见下表，程序判断请以它为准
`error.message`	string	中文说明，可直接展示给用户；措辞可能调整，请勿用于程序判断
`error.request_id`	string	请求编号
`error.details`	array	只在参数错误（`invalid_params`）时出现：逐个字段的 `{field, message}`

错误码表

以下错误都不扣点；任务受理后才失败的，冻结的点数全额退回。

HTTP	error.code	说明	建议处理
400	`bad_request`	文本模型接口的请求体不是合法的 JSON 对象（任务接口按缺少字段返回 invalid_params）	修正请求体后重试
401	`unauthorized`	缺少 Key，或 Key 无效、已停用、已过期、已删除；Key 所属账号已停用	检查 Key 是否正确、是否在有效期内
401	`signature_invalid`	Key 开启了「必须签名」但签名头缺失、签名不匹配、时间戳与服务器相差超过 300 秒，或随机串 10 分钟内重复	按「鉴权与签名」修正签名后重试
402	`insufficient_points`	点数（含授信额度）不足；不冻结、不开始生成	充值后重试
402	`key_quota_exceeded`	Key 的额度已用完（额度可按日 / 周 / 月自动重置）	在开放平台调整额度，或等待重置
403	`permission_denied`	该 Key 的可调模型不包含这个模型	在开放平台调整 Key 的可调模型
403	`account_limited`	账号已被限制发起生成	联系平台客服
403	`app_not_activated`	场景应用未开通或已过期（只对开放 API 与在线测试）	调用开通接口或在开放平台开通 / 续费后重试
404	`not_found`	任务、文件或接口不存在，或不属于本账号	检查编号与请求地址
404	`model_unavailable`	模型不存在、已下架、未对开放 API 开放，或对你的渠道等级不可见	换一个模型，或调用 GET /v1/models 查看可用模型
405	`method_not_allowed`	接口不支持该请求方法	检查请求方法（GET / POST）
409	`idempotency_conflict`	同一个 Idempotency-Key 已用于不同的模型或参数	换一个幂等键
409	`task_not_cancelable`	任务已结束，或已提交生成且无法取消	无需重试，以任务最终状态为准
422	`invalid_params`	参数错误：缺少必填字段、类型或取值超出范围（details 里逐字段说明）	按 details 修正参数后重试
422	`content_rejected`	提示词或参考素材未通过内容安全审核；不扣点	修改内容后重试
429	`rate_limited`	每分钟请求数超过 Key 的限速，响应头带 Retry-After（秒）	按 Retry-After 等待后重试
429	`concurrency_limited`	进行中的任务与文本调用数超过 Key 或账户的并发上限	等进行中的调用结束后再提交
500	`service_unavailable`	系统或模型服务繁忙（HTTP 500 或 503）；本次未扣点	稍后退避重试（如 1、2、4 秒）

任务失败原因

异步任务受理后才发生的失败，不以 HTTP 错误返回，而是体现在任务对象的 error.code 里（状态为 failed 或 canceled，查询接口本身返回 200）。冻结的点数全额退回。

error.code	说明	建议处理
`invalid_params`	参数不符合要求，请调整后重试（已退回点数）	修正参数后重新提交
`content_rejected`	内容未通过安全审核，请修改描述后重试（已退回点数）	修改提示词或素材后重新提交
`insufficient_points`	点数不足，任务未开始，未扣点	充值后重新提交
`timeout`	生成超时，已自动退回点数，请稍后重试	稍后重新提交
`service_unavailable`	该模型暂不可用，已自动退回点数	稍后重新提交，或换一个模型
`capacity_shortage`	平台算力暂时不足，已自动退回点数，请稍后再试	稍后重新提交
`generation_failed`	生成失败，已自动退回点数，请稍后重试	稍后重新提交
`no_result`	没有找到相关内容，换个链接或关键词再试试（已退回点数）	检查链接、编号或换个关键词后重新提交
`canceled`	任务已取消，点数已退回	无需处理

重试建议

rate_limited、concurrency_limited、service_unavailable 可以退避重试（如 1 秒、2 秒、4 秒……；rate_limited 按响应头 Retry-After）。提交任务时请带上 Idempotency-Key，避免重复创建。
其他 4xx 错误重试不会成功，请先按 message 修正请求。