錯誤碼

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）不受該輪詢限流影響。