错误码与排查

错误响应结构

RouterBee 的错误可能来自 API 网关或视频任务适配层，客户端应兼容两种常见结构。

网关错误

{
  "error": {
    "code": "insufficient_user_quota",
    "message": "Insufficient quota (request id: 20260819...)",
    "type": "new_api_error"
  }
}

任务错误

{
  "error": {
    "code": "upstream_rejected",
    "message": "Provider rejected the task.",
    "request_id": "req_...",
    "retryable": false
  }
}

不要只按错误消息文本编程。优先判断 HTTP 状态，再读取 error.code、error.type 和 error.message。错误字段应按可选字段处理。

HTTP 状态码

HTTP 状态	常见原因	是否直接重试	处理方式
400	JSON、字段、任务状态或参数组合不合法	否	修正请求后再提交
401	API Key 缺失、错误、禁用或过期	否	检查 Bearer 请求头和密钥状态
403	额度不足、模型/分组无权限、IP 不在白名单	否	检查余额、密钥权限和来源 IP
404	路径错误或任务不存在	否	检查接口地址和 task_id
413	请求体过大	否	缩小 JSON 或参考素材
429	请求、并发或轮询过于频繁	是	指数退避并降低并发
500	RouterBee 内部错误	有限重试	记录请求 ID并联系支持
502	上游暂时不可用或返回异常	有限重试	退避后重试，创建操作注意重复任务
503 / 504	服务繁忙或超时	有限重试	退避后重试

RouterBee 额度不足通常表现为 403，不要只按 402 编写客户端。

常见参数错误

model field is required / 模型不可用

• 请求必须包含 model。
• 使用 /v1/models 返回的 data[].id。
• 在模型广场核对模型详情，再用当前密钥的 /v1/models 响应确认模型 ID。
• 检查 API Key 是否限制了模型或选择了错误分组。

prompt is required

prompt 必须是非空字符串。只包含空格也会被拒绝。

invalid_seconds

• 使用正整数。
• 推荐写成 "seconds": "5"。
• 不要同时发送不同值的 seconds 和 duration。
• 确认所选模型支持该时长。

invalid_size

• 使用 WIDTHxHEIGHT，例如 1280x720。
• 必须是小写字母 x，不能写 ×、*、720p 或 16:9。
• 格式正确后仍需确认模型支持该尺寸。

参考图不可用

• 使用可公开读取或已授权的 HTTPS 图片地址。
• 确认 URL 返回图片内容，而不是 HTML 登录页。
• 保证 URL 在上游读取期间不过期。
• 检查图片格式、大小和模型的图生视频能力。

任务一直是 queued

• 每 3–5 秒查询一次，不要重复创建。
• 检查模型渠道是否繁忙。
• 为客户端设置最长等待时间，但停止等待不等于任务已经失败。
• 稍后仍可使用原 task_id 查询。
• 长时间无变化时保存任务 ID和请求 ID联系支持。

任务为 completed 但没有 video_url

这是正常情况。状态接口不保证返回视频 URL。请调用：

GET /v1/videos/{task_id}/content

并继续携带同一个 API Key。

下载得到 JSON 而不是 MP4

先查看 HTTP 状态和 Content-Type。常见原因：

• 任务尚未完成。
• API Key 缺失或无权访问该任务。
• task_id 错误。
• 上游视频暂时无法获取。

使用 curl --fail-with-body 查看错误，不要把错误 JSON 当成 .mp4 文件。

创建请求超时

创建超时不等于服务端没有受理。当前不应依赖 Idempotency-Key 进行全链路去重：

1. 检查任务日志和使用日志。
2. 确认是否已经产生任务或扣费记录。
3. 能找到任务 ID时继续查询该任务。
4. 确认没有创建成功后再提交新任务。

联系支持时提供

• 请求发生时间和时区
• HTTP 状态码
• 响应头 X-Oneapi-Request-Id
• task_id
• 模型名称
• 已脱敏的请求和完整错误响应

不要发送 API Key、管理员令牌或供应商密钥。