Blog/YouTube download API statuses and errors: what to retry and what to record
OverviewAll posts
Reference

YouTube download API statuses and errors: what to retry and what to record

Map each Tornado API job status and error type to one action in your code: wait, use the file, retry, or record the outcome and move on.

VTornado API team
Covered in this article
The eight job statuses
Technical errors versus content issues
A retry policy that does not waste work
6 min reading time
Published November 14, 2026
VProduct guides by Velys Software

A download job ends in one of a few states, and each state calls for a different action. Code that treats every non-success as "retry" wastes time on videos that will never download and hides the failures that deserve attention. This reference maps each Tornado API status to what your application should do.

The eight statuses

GET /jobs/{id} returns a status field with one of these values:

StatusMeaningYour action
PendingIn the queueWait
ProcessingBeing downloaded or preparedWait; step shows the current stage
CompletedFile deliveredUse the delivery URL or read from your bucket
FailedTechnical errorRetry once, then investigate
WarningContent issue: private, members-only, region-blocked, unavailableRecord the reason; do not retry as is
SkippedContent cannot be processed, for example a DRM-protected audio episodeRecord and move on
CancelledCancelled by your applicationNone
CancelledByAdminCancelled by an operatorContact support with the job ID

Pending and Processing are the only non-final states. Everything else is final for that job.

Two kinds of failure

When a job ends as Failed, Warning or Skipped, the response also carries error, a readable message, and error_type, which has two values:

  • error: a technical failure on the way to the file, such as a connection problem or a refusal by the source platform.
  • warning: a property of the content itself. The video is private, removed, reserved for members, blocked in a region or age-restricted.
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Failed",
  "s3_url": null,
  "error": "Video unavailable",
  "error_type": "warning"
}

Branch on error_type before the status name. A warning will produce the same result an hour later, because nothing about the video has changed. An error may succeed on a new attempt.

A retry policy that does not waste work

import requests

API = "https://api.tornadoapi.io"
HEADERS = {"x-api-key": "YOUR_API_KEY"}
FINAL = {"Completed", "Failed", "Warning", "Skipped", "Cancelled", "CancelledByAdmin"}

def next_action(job: dict) -> str:
    status = job["status"]
    if status not in FINAL:
        return "wait"
    if status == "Completed":
        return "use_file"
    if job.get("error_type") == "error":
        return "retry"
    return "record"

def retry(job_id: str) -> None:
    response = requests.post(f"{API}/jobs/{job_id}/retry", headers=HEADERS, timeout=30)
    response.raise_for_status()

Three rules keep this policy safe:

  • Bound the retries. Retry a technical failure once or twice with a pause, then stop and keep the job ID for investigation. POST /jobs/{id}/retry reruns the job with the same parameters.
  • Never resubmit after a timeout. If the request that creates a job times out, the job may exist. Look it up before creating another one, or you may pay for the same file twice. Resuming after a restart shows how to store job IDs for this.
  • Record content outcomes as results. Store the error message next to the source URL. A private video is an answer for your user, not an incident for your team.

What failures cost

A job that does not complete is not billed. Only delivered files count toward billable volume, so a batch with restricted videos costs what its completed jobs cost.

Age-restricted videos

An age-restricted video ends as a content issue by default. The create-job reference documents an optional cookies field for supplying the session of an age-verified account that you control. Leave it out unless you need this case.

Batches

For work submitted through the bulk endpoint, apply the same mapping per job. A batch is finished when every job is final, not when every job is Completed. Recovering a batch after partial failures covers the bookkeeping, and failures and retries explains the reasoning behind these outcomes.

The authoritative field list is in the job status reference.