Errors and status codes

HTTP errors

Error responses have this shape:

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

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:

{
    "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.