任务失败原因与处理建议 · 十方MAAS 开发者文档

概览

参数或素材不符合要求时，错误说明会给出具体原因和修改建议。服务暂不可用时统一返回 service_unavailable，请稍后重试，无需修改素材或账户配置。请求尚未受理时对应 HTTP 503；已受理任务的查询仍返回 HTTP 200，请读取任务 status 和 error。

任务列表、详情、任务查询和回调使用相同的错误说明。程序按 error.code 判断类型，向用户展示 error.message。修正参数后创建新任务；状态仍在核实时请继续查询，避免重复提交。

如何读取失败原因

查询返回 HTTP 200 时仍须检查 status。下面为失败响应的关键字段；完整结构见任务查询 API。

{
  "id": "job_example",
  "status": "failed",
  "output": null,
  "error": {
    "code": "input_media_unavailable",
    "message": "无法下载输入素材，请检查链接是否过期、是否可公开访问后重新提交。"
  }
}

任务失败码

平台错误码	原因与建议
`input_parameter_missing`	请求缺少必要参数，请按接口要求补齐后重新提交。
`input_parameter_conflict`	参数组合与当前处理模式不兼容，请检查参数和素材组合后重新提交。
`input_task_type_mismatch`	提示词、素材与指定的任务类型不一致，请调整后重新提交。
`media_probe_failed`	无法读取视频信息，请确认视频地址有效且支持分段读取。
`media_probe_busy`	视频信息读取繁忙，请稍后重新提交。
`insufficient_balance`	账户可用余额不足，请充值后重新提交。
`outstanding_balance`	账户存在待补款任务，请充值结清后再提交。
`account_disabled`	客户账户已暂停，请联系平台。
`cancellation_failed`	此次取消未成功，任务继续处理中，请查询最终结果。
`verification_pending`	任务结果正在核实，无需重新提交，请稍后查询或联系平台。
`provider_bad_request`	请求参数或素材不符合要求，请检查后重试。
`material_compliance_failed`	素材检查未通过，请检查素材是否可访问且符合内容要求。
`provider_content_rejected`	提示词或素材不符合内容要求，请调整后重试。
`service_unavailable`	服务暂不可用，请稍后重试；如持续失败，请联系平台。
`provider_timeout`	视频处理超时，请稍后重试。
`provider_submit_uncertain`	任务提交状态暂无法确认，请提供任务 ID 联系平台排查。
`provider_failed`	视频处理失败，请提供任务 ID 联系平台排查。
`result_storage_failed`	结果保存失败，请提供任务 ID 联系平台排查。
`input_resolution_unsupported`	请求或素材分辨率不符合要求，请按接口要求调整后重新提交。
`input_duration_unsupported`	素材或请求的视频时长不符合要求，请按接口要求调整时长后重新提交。
`input_frame_rate_unsupported`	视频帧率不符合要求，请按接口要求调整帧率后重新提交。
`input_format_unsupported`	素材格式或编码不支持，请转换为接口支持的格式后重新提交。
`input_file_too_large`	素材文件过大，请压缩文件或缩短时长后重新提交。
`input_media_unavailable`	无法下载输入素材，请检查链接是否过期、是否可公开访问后重新提交。
`input_media_invalid`	无法解析输入素材，请检查文件是否完整、可正常播放或打开后重新提交。

修正与排查

分辨率错误在能够确认限制时会说明本次输入视频的短边、长边范围；范围以本次响应为准。历史记录缺少具体原因时只能提供统一提示。

排查时提供任务 ID、错误码和请求时间。新任务使用新的幂等键；网络异常但尚未确认是否受理时，按幂等与重试处理。