Errors & limits
Error format, status codes, rate limits and retry advice for the VideoUpscaler API.
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 600 seconds | 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 | 600 seconds |
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.