错误排查

按 HTTP 状态、任务状态和账务状态处理失败，避免重复提交。

先记录域名、接口路径、模型、HTTP 状态、响应正文和 Request ID。视频还需保存任务 ID。不要在故障时反复发送同一个生成请求。

常见 HTTP 状态

HTTP	常见原因	处理
400	参数不合法、视频分辨率或时长不支持	按对应接口参数修正再提交
401	Key 缺失、错误或认证格式不对	检查请求头、完整密钥和环境变量
402	企业钱包余额不足	查看企业钱包余额与预扣需求
403	跨站 Key、IP/权限限制、Key 额度或状态问题	读取具体错误，核对企业 Key 和企业域名
404	路径或模型错误、任务不存在或无权访问	查实时目录和原任务 ID，不要猜 ID
409	任务当前状态不允许操作	查询原任务，等待状态确认
429	请求频率或容量限制	降低并发，按 `Retry-After`（如有）等待
500 / 502 / 503 / 504	服务异常、上游错误、排队或文件交付中	保留错误，区分查询重试与生成请求重提

具体错误消息比单一状态码更精确。例如余额或 Key 额度相关错误可能走不同状态码。

读取错误正文

生成接口可能返回如下结构，示例值：

{"error":{"message":"请求参数不符合所选模型要求","type":"invalid_request_error","code":"invalid_request"}}

认证阶段也可能返回 {"success":false,"message":"...","code":"..."}。客户端应兼容这两种形式，不能只解析 choices。

何时重试

查询目录、查询任务、查询用量可在短暂网络错误后有上限地重试，并逐步延长间隔。对于生成请求，先判断是否明确未执行。已经拿到任务 ID 时只查询该 ID；若创建请求超时且没有 ID，应先查控制台和请求记录，必要时联系支持确认。

文本流式输出已收到内容后断开，可能已经产生用量。不要将这次请求自动当作失败零费用并全量重发。应用需决定是否保留部分答案以及如何告知使用者。

视频完成但下载失败

video_delivery_pending 表示文件仍在保存，按响应的 Retry-After 等待，再下载原任务。video_delivery_failed 需要保留任务 ID 联系支持。过期或已删除的结果可能无法再次下载；再次提交会创建新的收费任务。

seconds 应为字符串，如 "5"；整数或自动时长使用顶层 duration。Mini/Fast 不支持 1080p；2.0/2.5 不支持 480p。2.5 首帧、首尾帧与显式编辑/延长需要 adaptive，显式编辑还需要 duration: -1。参考素材数量与字段见 Seedance。批量参数 n 当前只支持 1；写 2–4 返回 video_batch_unavailable，非法值返回 invalid_video_parameters。

上游拒绝参考素材约束

video_provider_constraint 表示上游按自己的规则拒绝了参考素材，message 按站点语言给出，并引用本站为该型号配置的上限。参考素材的合计时长与单文件体积由上游判定，客户端应先按 Seedance 能力表自查再提交，不要靠反复重提试探。

提交给支持的最小信息

提供请求时间和时区、企业域名与路径、模型、HTTP 状态、Request ID、任务 ID、脱敏错误及预期行为。涉及费用时附请求结算状态，涉及充值时附订单号。移除 Key、Cookie、个人敏感内容和签名 URL。