错误结构与错误码 · 十方MAAS 开发者文档

概览

请求未被受理时，返回相应 HTTP 错误状态与以下结构。校验失败为 422；请求体超过上限为 413。响应头 X-Request-ID 可用于排查。

错误响应结构

{
  "error": {
    "code": "invalid_request",
    "message": "请求参数校验失败",
    "request_id": "req_example",
    "details": null
  }
}

error.code 和 error.message 为字符串，程序按 code 判断，message 用于说明；request_id 为字符串或 null。details 可能缺省、为 null 或具体校验信息；422 时通常为数组，条目的 loc 指出字段位置、msg 说明原因、type 表示校验类型。以下列出常见情况：

HTTP 状态与错误码

HTTP	错误码	含义与处理
400 / 422	invalid_request	字段、取值或参数组合不符合要求；根据 details 修正。
413	invalid_request	请求体超过 42 MiB；减少 Base64 素材体积或改用 URL。
401	unauthorized / key_disabled / key_expired	检查 Bearer 密钥、有效期和启用状态。
403	account_disabled / product_forbidden / api_not_configured / unsupported_api_parameters	账户暂停、未获授权或未开通对应规格，联系管理员。
402	insufficient_balance	您在本平台的可用余额不足，充值后再提交。
429	quota_exceeded	Key 对应 API 的调用次数额度耗尽，调整额度后再提交。
429	queue_full / rate_limited / media_probe_busy	容量已满、提交过于频繁或视频信息读取繁忙；按 Retry-After 延迟重试。
409	idempotency_conflict	同一幂等键被用于不同参数；确认是否为新业务任务。
404	task_not_found	核对任务 ID，并使用创建该任务的同一把 Key。
409	cancellation_unavailable / task_busy	当前无法取消，或任务正在更新；继续查询状态。
422 / 504	media_probe_failed / media_probe_timeout	无法读取视频信息 / 读取超时；检查素材地址与格式，超时可稍后重试。
503	pricing_unavailable / route_unavailable / service_paused / service_unavailable	服务暂不可用，稍后重试；计费未配置或持续不可用时联系管理员。

任务失败与下载错误

已受理的任务执行失败时，查询仍返回 HTTP 200，任务 status 为 failed，error 为 {"code": "…", "message": "…"}，详见任务失败原因与处理建议。结果下载接口的错误使用 {"detail": "说明"}；HTTP 状态见下载结果。