错误处理

两层错误

请求层错误：HTTP 非 2xx，可能在提交前发生。响应可能使用 error.code / error.message，也可能是兼容格式的顶层 code / message。不要只支持一种错误外壳。

任务层错误：查询请求 HTTP 200，但 status: "failed"，错误位于 error。这是终态，停止查询，不要因 HTTP 200 而把它当作生成成功。

常见情况

情况	建议处理
400 / 422，参数或素材被拒绝	检查 error.message、模式、尺寸、格式、时长；修改后再提交
400，model_endpoint_not_supported	当前模型不支持所用接口；按报错给出的端点和文档修改路径及请求体，不要原样重试。NAI、工作流模型不能直接使用聊天 messages 格式；支持聊天生图的线路不受此限制
401 / 403	处理 Key 或权限，停止高频查询
404，任务不可查询	检查任务 ID、媒体类型路径和账户权限
429	降低频率，按 Retry-After 等待；不循环重发生成
查询出现网络错误、502 / 504	可以有限退避重试同一个 GET
POST 网络超时	结果未知，可能已创建任务；先查任务记录，避免重复提交
status: failed	展示任务错误并停止轮询；如需重试，创建新任务
成功但链接打不开	完整保留签名参数，检查时效、跨域与下载网络；及时保存结果

供应商错误码未必与用户请求 HTTP 状态一一对应。状态码写在错误文案里时，不要仅凭字符串数字判定是否继续轮询，以公开任务 status 为准。

容易混淆的参数

• Seedance 首尾帧输出比例跟随输入帧，优先使用 adaptive，不要强制指定不匹配比例。
• Seedance 2.5 单视频编辑需要 duration: -1 和 adaptive，普通参考生成不需要。
• Wan 3 EP 有「输入视频 + 输出 ≤ 30 秒」限制，不能只检查输出。
• 参考音频不是「生成音频」开关，而且不能单独代替图像 / 视频参考。
• 香蕉 default 暂不支持 4K；GPT 的 quality、moderation 不能直接照搬给香蕉。
• 自定义尺寸传 resolution: custom 与 size，不要再传另一个冲突比例。
• 大段 Base64、blob: 和网页分享链接容易造成上传或下载失败，优先使用直接可访问的 HTTPS 文件。

向支持人员提供什么

提供任务 ID、请求时间、模型、所用分组、HTTP 状态、错误码与消息，以及去掉密钥和大段编码后的请求 JSON。不要公开 Key、Authorization、私有图片或含敏感凭证的链接。

本文错误文案仅为说明，不构成固定枚举。需要稳定处理时优先使用 HTTP 状态与 status / error.code，保留未知错误兜底展示。