Error format, status codes, rate limits and retry advice for the VideoUpscaler API, including how to retry an upscale safely with an Idempotency-Key.

Error format

Every error has the same JSON shape. Use code in your code; message is for people and may change.

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

Status codes

Status	Code	Meaning	Retry?
`400`	`invalid_request`	The request is malformed	No — fix the request
`401`	`unauthorized`	Missing or invalid API key	No
`402`	`insufficient_credits`	Not enough credits	After buying credits
`403`	`paid_plan_required`	The account has never bought credits or subscribed	After buying credits
`403`	`invalid_upload_token`	Upload URL invalid or expired	Request a new upload URL
`403`	`invalid_stream_token`	Event stream URL invalid or expired	Open `/tasks/{id}/events` again
`404`	`not_found`	No such task in your account	No
`409`	`idempotency_conflict`	`Idempotency-Key` reused with other parameters	Use a new key
`411`	`invalid_request`	Upload `PUT` without a body or `Content-Length`	No — fix the request
`413`	`file_too_large`	Video over the size limit	No
`422`	`video_fetch_failed`	`video_url` couldn't be downloaded	After fixing the URL
`422`	`unsupported_video`	Not a readable MP4, MOV or WebM	No
`422`	`video_too_long`	Video longer than the limit for its resolution	No
`422`	`video_not_found`	Nothing was uploaded at this `video_url`	After the upload finishes
`429`	`rate_limited`	Too many requests	Yes, after `Retry-After` seconds
`500`	`internal_error`	Something went wrong on our side	Yes, with the same `Idempotency-Key`
`502`	`upstream_error`	Processing couldn't start; any charge was refunded	Yes, with a new `Idempotency-Key`
`504`	`upstream_timeout`	Downloading `video_url` took too long	Yes, or use a faster host

Limits

Limit	Value
Requests	About 120 per minute per API key
Video length	1200 seconds at 1080p, 600 seconds at 2k and 4k
Remote `video_url` size	500MB
Uploaded file size	100MB
Upload URL lifetime	1 hour
Active API keys	20 per account

Retrying safely

Always send an Idempotency-Key to /upscale. If a request times out or you get a 500 or 504, retry with the same key: you get the task that was already created instead of a second charge.

A 502 upstream_error is different: the task was created, failed to start and was refunded, so the same key keeps returning that failed task. Retry with a new key.

Errors & limits

Error format

Status codes

Limits

Retrying safely

On this page