错误码

Video API 各端点的错误都使用同一个 JSON 结构：


{
  "error": {
    "code": "...",
    "message": "..."
  }
}

HTTP 状态码表示问题的类别；error.code 是稳定的字符串标识，供程序分支判断。请始终按 error.code 匹配，不要解析 error.message 文案。

错误码表

HTTP	code	含义
400	`invalid_request`	参数缺失或取值非法
400	`invalid_callback_url`	`callback_url` 非 HTTPS 或指向私网（被 SSRF 校验拦截）
400	`references_conflict`	`frame_images` 与 `input_references` 在同一请求中同时传（互斥）
400	`too_many_references`	`input_references` 超出上限（图 > 9 / 音 > 3 / 视 > 1）
400	`cancel_not_supported`	上游 provider 不支持中断该任务
400	`cancel_failed`	任务已处于终态，无法取消
401	`unauthorized` / `invalid_api_key`	鉴权失败
401	`upstream_auth_failed`	上游供应商鉴权失败
402	`insufficient_credits`	余额不足，无法受理任务
404	`not_found`	任务不存在，或无访问权限
404	`model_not_found`	模型不存在
429	`rate_limited`	频率超限（轮询限流或上游限流）
502	`upstream_error` / `route_error`	上游供应商错误 / 路由失败
500	`internal_error`	内部错误

references_conflict 与 too_many_references 是请求体校验错误，具体上限见创建视频任务。cancel_not_supported 与 cancel_failed 的判定见取消任务。not_found 对”任务不存在”和”任务属于其他 API Key”两种情况统一返回——二者故意不作区分。

402 余额不足

insufficient_credits 仅在创建任务（POST /v1/videos）时返回。开启预扣后，ofox 会在受理任务前按请求的分辨率与时长预估费用；若预估额超过账户余额，请求会被立即拒绝——任务不会入库，也不会产生扣费。


{ "error": { "code": "insufficient_credits", "message": "..." } }

Video API 的 402 只会返回 insufficient_credits 这一个 code。接入方处理这一个 code、充值后重试即可。

429 频率限制

rate_limited 同时覆盖 GET /v1/videos/{id} 的按 Key 轮询限流与上游限流。触发轮询限流时，响应会带 Retry-After 头：


HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

请尊重 Retry-After 头，退避后再重试。若轮询过于频繁，改用 Webhook 通知——由 ofox 在终态时主动推送，彻底避开轮询限流。创建任务（POST）与取消任务（DELETE）不受该轮询限流影响。