错误处理

错误响应

接口错误通常使用 JSON 返回。客户端应同时记录 HTTP 状态码、错误代码和消息，但必须对令牌与输入 URL 脱敏。

常见形式：

{
  "error": {
    "message": "错误说明",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

视频任务也可能在提交成功后异步失败：

{
  "id": "task_xxxxxxxxxxxx",
  "status": "failed",
  "error": {
    "code": "upstream_error_code",
    "message": "上游返回的失败原因"
  }
}

是否重试

场景	是否建议重试
网络超时且无法确认是否已创建任务	谨慎；先按业务幂等记录检查，避免重复扣费
401、403	否；先修复认证或权限
参数错误、内容审核失败	否；先修正请求或处理授权问题
429	可以；使用指数退避并检查额度
临时 5xx	可以；有限次数指数退避
任务处于 queued / in_progress	不要重新提交；继续低频查询原任务

客户端建议

• 为每次业务生成保存本站公开任务 ID。
• 连接超时不等同于任务创建失败。
• 重试设置最大次数和指数退避。
• 日志中只保留脱敏请求信息。
• 下载结果后保存到自己的持久存储，不长期依赖临时签名 URL。