错误格式

所有错误都使用相同的 JSON 结构。请在代码中依据 code 判断；message 是给人看的，内容可能会变。

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

状态码

状态码	错误码	含义	是否重试？
`400`	`invalid_request`	请求格式有误	否——请修正请求
`401`	`unauthorized`	API 密钥缺失或无效	否
`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 密钥缺失或无效	否
`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 重试。