錯誤格式

所有錯誤都使用相同的 JSON 結構。請在程式中判斷 code；message 是給人看的，內容可能會變動。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this video. Buy credits to continue."
  }
}

狀態碼

狀態碼	錯誤碼	意義	可以重試嗎？
`400`	`invalid_request`	請求格式錯誤	否，請修正請求
`401`	`unauthorized`	缺少 API 金鑰或 Key 無效	否
`402`	`insufficient_credits`	點數不足	購買點數後
`403`	`paid_plan_required`	帳號從未購買點數或訂閱	購買點數後
`403`	`invalid_upload_token`	上傳 URL 無效或已過期	重新取得上傳 URL
`403`	`invalid_stream_token`	事件串流 URL 無效或已過期	重新開啟 `/tasks/{id}/events`
`404`	`not_found`	你的帳號中沒有這個任務	否
`409`	`idempotency_conflict`	`Idempotency-Key` 已搭配其他參數使用過	改用新的 Key
`411`	`invalid_request`	上傳的 `PUT` 沒有請求本文或缺少 `Content-Length`	否，請修正請求
`413`	`file_too_large`	影片超過大小上限	否
`422`	`video_fetch_failed`	無法下載 `video_url`	修正 URL 後
`422`	`unsupported_video`	不是可讀取的 MP4、MOV 或 WebM	否
`422`	`video_too_long`	影片長度超過 600 秒	否
`422`	`video_not_found`	這個 `video_url` 尚未上傳任何檔案	上傳完成後
`429`	`rate_limited`	請求過於頻繁	可以，等待 `Retry-After` 秒後
`500`	`internal_error`	我們這邊發生錯誤	可以，請沿用相同的 `Idempotency-Key`
`502`	`upstream_error`	無法開始處理；已扣的點數都會退還	可以，但要換一個新的 `Idempotency-Key`
`504`	`upstream_timeout`	下載 `video_url` 花費太久	可以，或改用速度較快的主機

呼叫 /upscale 時一律帶上 Idempotency-Key。如果請求逾時或收到 500 或 504，請用相同的 Key 重試：你會拿到先前已建立的任務，而不會被重複扣點。

502 upstream_error 則不同：任務已經建立，但啟動失敗並已退點，用相同的 Key 會一直拿到這個失敗的任務。請換一個新的 Key 重試。

錯誤與限制

VideoUpscaler API 的錯誤格式、狀態碼、速率限制與重試建議。

所有錯誤都使用相同的 JSON 結構。請在程式中判斷 code；message 是給人看的，內容可能會變動。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this video. Buy credits to continue."
  }
}

狀態碼	錯誤碼	意義	可以重試嗎？
`400`	`invalid_request`	請求格式錯誤	否，請修正請求
`401`	`unauthorized`	缺少 API 金鑰或 Key 無效	否
`402`	`insufficient_credits`	點數不足	購買點數後
`403`	`paid_plan_required`	帳號從未購買點數或訂閱	購買點數後
`403`	`invalid_upload_token`	上傳 URL 無效或已過期	重新取得上傳 URL
`403`	`invalid_stream_token`	事件串流 URL 無效或已過期	重新開啟 `/tasks/{id}/events`
`404`	`not_found`	你的帳號中沒有這個任務	否
`409`	`idempotency_conflict`	`Idempotency-Key` 已搭配其他參數使用過	改用新的 Key
`411`	`invalid_request`	上傳的 `PUT` 沒有請求本文或缺少 `Content-Length`	否，請修正請求
`413`	`file_too_large`	影片超過大小上限	否
`422`	`video_fetch_failed`	無法下載 `video_url`	修正 URL 後
`422`	`unsupported_video`	不是可讀取的 MP4、MOV 或 WebM	否
`422`	`video_too_long`	影片長度超過 600 秒	否
`422`	`video_not_found`	這個 `video_url` 尚未上傳任何檔案	上傳完成後
`429`	`rate_limited`	請求過於頻繁	可以，等待 `Retry-After` 秒後
`500`	`internal_error`	我們這邊發生錯誤	可以，請沿用相同的 `Idempotency-Key`
`502`	`upstream_error`	無法開始處理；已扣的點數都會退還	可以，但要換一個新的 `Idempotency-Key`
`504`	`upstream_timeout`	下載 `video_url` 花費太久	可以，或改用速度較快的主機

呼叫 /upscale 時一律帶上 Idempotency-Key。如果請求逾時或收到 500 或 504，請用相同的 Key 重試：你會拿到先前已建立的任務，而不會被重複扣點。

502 upstream_error 則不同：任務已經建立，但啟動失敗並已退點，用相同的 Key 會一直拿到這個失敗的任務。請換一個新的 Key 重試。