Error Handling

DownAria and Backend return structured errors so clients can decide retry logic and user-facing messages.

Error Envelope

{
  "success": false,
  "response_time_ms": 184,
  "error": {
    "kind": "download_failed",
    "code": "download_command_failed",
    "message": "download failed",
    "retryable": true,
    "request_id": "4e7bb8f2f23c42a1"
  }
}

Common Error Codes

Code	Kind	HTTP	Retryable
invalid_request_body	invalid_input	400	no
extract_url_required	invalid_input	400	no
download_request_failed	upstream_failure	502	yes
download_command_failed	download_failed	500	yes
merge_validation_missing_audio	merge_failed	500	no
job_not_found	invalid_input	404	no
artifact_missing	invalid_input	404	no
timeout	timeout	504	yes

invalid_request_body

Kind

invalid_input

HTTP

400

Retryable

extract_url_required

Kind

invalid_input

HTTP

400

Retryable

download_request_failed

Kind

upstream_failure

HTTP

502

Retryable

yes

download_command_failed

Kind

download_failed

HTTP

500

Retryable

yes

merge_validation_missing_audio

Kind

merge_failed

HTTP

500

Retryable

job_not_found

Kind

invalid_input

HTTP

404

Retryable

artifact_missing

Kind

invalid_input

HTTP

404

Retryable

timeout

Kind

timeout

HTTP

504

Retryable

yes

Reliability Features

⏱️ Request Timeouts

30-second timeout on all API calls prevents hanging requests

🔄 Circuit Breaker

Automatic failure detection with 5 failure threshold and 30s recovery timeout

📊 Exponential Backoff

Smart polling intervals: 1s → 2s → 4s → 8s → 15s max

🎯 Request Deduplication

Prevents duplicate downloads of the same item

⚡ Concurrent Limiting

Max 5 concurrent batch downloads to prevent browser overwhelm

💾 Memory Safety

Streaming approach for files >100MB to prevent memory exhaustion

Retry Rule

Retry only when `error.retryable` is `true`, or when timeout/upstream errors are explicitly marked as temporary.

Support Rule

Always log `request_id` in client telemetry or bug reports so backend logs can correlate failures quickly.