响应与错误码

区分 HTTP 状态、业务响应与异步任务状态，可靠地处理每一次调用。

统一响应结构

ret=0 表示业务成功，ret=-1 表示业务失败；业务数据位于 data.ent。

json

{
  "ret": -1,
  "code": 70001,
  "msg": "积分不足，请充值或减少生成数量"
}

HTTP 200 不代表业务成功；创建任务成功也不代表任务完成。异步结果还需检查任务 status。

错误码	含义	处理建议
`10000`	参数错误	检查必填项、字段类型与来源链接；幂等键不得复用于不同输入。
`10002`	用户身份缺失	核对 Authorization: Bearer <API Key>。
`10008`	用户未注册	先在 Popto 注册，再为当前账号创建 API Key。
`10009`	API Key 不匹配	在工作台 API 密钥页面核对当前环境与密钥。
`10110 / 10111`	任务 ID 无效或过多	task_ids 清理和去重后必须为 1–50 个。
`50109`	工作流操作忙	先等待当前步骤结束，查询 workflow/info，以原键恢复待处理操作。
`50110`	最终审阅未通过	修复审稿问题，核对目标账号、正文与图片，重新终审并排版。
`50111`	操作结果待恢复	保留原请求及幂等键进行恢复，避免重复创建外部草稿。
`50112`	图片未准备完成	等待生图完成，使用当前工作流匹配的 image_id 和 image_url。
`50113`	公众号或素材归属错误	重新查询 account/list，并为目标账号上传素材。
`50114`	跟创能力未启用	联系服务支持确认当前环境的跟创能力已开放。
`70001`	账户积分不足	补充积分或减少生成量，停止自动重试。
`70010`	批量视频数量超出套餐上限	按配置展开后的外观视频数量计算本次批量大小，减少选择或升级套餐后再生成。
`70013`	本次预算不足	重新查询 quote，明确调整 max_credits 后以新键提交。

鉴权层可能直接返回 HTTP 401 或其他非 200 响应。先检查 HTTP 状态，再解析业务响应；保留请求信息用于排查。

结果未知时如何恢复

跟创写操作超时或返回 50111 时，使用 workflow/info 查询操作记录，再用相同请求与原幂等键恢复。独立工具接口没有幂等键，不应在超时后无条件重复提交。