# Errors and status codes

Distinguish an HTTP failure from a failed background job.

## HTTP errors

Error responses have this shape:

```json
{
    "error": {
        "code": "JOB_CAPACITY_EXCEEDED",
        "message": "Too many pending downloads. Wait for a job to finish before retrying.",
        "requestId": "req_example"
    }
}
```

| HTTP status | Common codes                                             | Action                                                                 |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
| 400         | `VALIDATION_ERROR`, `BAD_REQUEST`, `BATCH_TOO_LARGE`     | Fix the request                                                        |
| 401         | `AUTH_REQUIRED`, `AUTH_INVALID`                          | Check the authentication method, key, and expiry                       |
| 403         | `ORIGIN_FORBIDDEN`, `LIMIT_EXCEEDED`, `SESSION_REQUIRED` | Check browser origin, byte allowance, or required session type         |
| 404         | `JOB_NOT_FOUND`, `FILE_NOT_FOUND`, `PLAYLIST_NOT_FOUND`  | Check ID and owning account; inaccessible private resources are hidden |
| 409         | `IDEMPOTENCY_CONFLICT`, `JOB_NOT_CANCELLABLE`            | Resolve the conflict instead of blind retry                            |
| 429         | `RATE_LIMITED`, `JOB_CAPACITY_EXCEEDED`                  | Back off or wait for capacity                                          |
| 500 / 503   | Service-dependent                                        | Retry a temporary outage with a bounded delay                          |

The listed codes are common examples, not an exhaustive enumeration. Libraries may reject malformed bodies before application validation. Preserve `requestId` for support.

## Background failure

A status lookup can return `200` for a job that failed:

```json
{
    "job": {
        "id": "job_example",
        "status": "failed",
        "error": {
            "code": "WORKER_FAILED",
            "message": "The source could not be downloaded."
        },
        "result": null
    }
}
```

Inspect the job's `status` and `error`, not only `response.ok`. Do not request files from a failed job or turn a partial collection into a successful response.

## Transport failures

A browser network error has no HTTP status visible to JavaScript. Check connectivity, timeout, and CORS. The website's generic connection message cannot identify the cause alone. See [troubleshooting](/docs/en/troubleshooting).