---
title: "YouTube download API statuses and errors: what to retry and what to record"
description: "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."
url: https://tornadoapi.io/blog/youtube-download-job-statuses-and-errors
published: 2026-11-14
---

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

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:

| Status | Meaning | Your action |
|---|---|---|
| `Pending` | In the queue | Wait |
| `Processing` | Being downloaded or prepared | Wait; `step` shows the current stage |
| `Completed` | File delivered | Use the delivery URL or read from your bucket |
| `Failed` | Technical error | Retry once, then investigate |
| `Warning` | Content issue: private, members-only, region-blocked, unavailable | Record the reason; do not retry as is |
| `Skipped` | Content cannot be processed, for example a DRM-protected audio episode | Record and move on |
| `Cancelled` | Cancelled by your application | None |
| `CancelledByAdmin` | Cancelled by an operator | Contact 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.

```json
{
  "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

```python
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](https://tornadoapi.io/blog/resume-media-jobs-after-worker-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](https://tornadoapi.io/blog/recover-media-batch-partial-failures) covers the bookkeeping, and [failures and retries](https://tornadoapi.io/blog/media-job-failures-and-retries) explains the reasoning behind these outcomes.

The authoritative field list is in the [job status reference](https://docs.tornadoapi.io/api-reference/jobs/get-status).
