錯誤碼
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」兩種情況統一返回——二者故意不作區分。
real_person 圖片預處理錯誤
當 real_person: true 因傳入圖片問題導致預處理失敗時，API 返回 HTTP 400，且 error.code 為 invalid_request。error.message 末尾會包含以下穩定原因短碼，並標出出錯引用位置，例如 input_references[0]：
| 原因短碼 | 處理方式 |
|---|---|
bad_data_uri | data: URI 格式錯誤，或 base64 內容無效 |
download_failed | 因連線、逾時或存取控制問題無法下載圖片 |
unreachable | 圖片 URL 返回非成功 HTTP 狀態 |
not_image | 下載內容不是支援且可解碼的圖片 |
too_large | 圖片超過檔案大小、像素數或單次請求的處理上限 |
{
"error": {
"code": "invalid_request",
"message": "real_person image processing failed — input_references[0]: ... (not_image)"
}
}程式分支仍應判斷 error.code；原因短碼和引用位置用於修正輸入或排查問題。
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）不受該輪詢限流影響。