Reference
Error Codes
Complete reference of Risuko download engine error codes.
Risuko uses numeric error codes to identify download failures. Each error code belongs to a category based on its numeric range.
When a download fails, the error code and a human-readable message are stored on the task and displayed in the UI. In the task's JSON representation they appear as errorCode (the code as a string, e.g. "315") and errorMessage; both are omitted when the task has no error and cleared when it restarts.
Codes are assigned by pattern-matching the failure message text. Messages that match no pattern fall back to code 100.
| Range | Category |
|---|
| 1xx | General errors |
| 2xx | Network errors |
| 3xx | HTTP errors |
| 4xx | File system errors |
| 5xx | Protocol-specific errors |
| 9xx | Internal engine errors |
| Code | Name | Description |
|---|
| 100 | Unknown | An unclassified error occurred. Check the error message for details. |
| Code | Name | Description |
|---|
| 200 | DNS Resolution Failed | Could not resolve the hostname. Verify the URL and your DNS settings. |
| 201 | Connection Refused | The remote server refused the connection. The server may be down or the port may be blocked. |
| 202 | Connection Reset | The connection was reset by the remote host during transfer. |
| 203 | Connection Timeout | The connection timed out before a response was received. |
| 204 | Network Unreachable | No network route to the host. Check your internet connection. |
| 205 | TLS Handshake Failed | SSL/TLS negotiation failed. The server's certificate may be invalid or the TLS version unsupported. |
| 206 | Proxy Connection Failed | Could not connect through the configured proxy server. |
| Code | Name | Description |
|---|
| 300 | Unauthorized | HTTP 401 — The server requires authentication credentials. |
| 301 | Forbidden | HTTP 403 — Access to the resource is denied. |
| 302 | Not Found | HTTP 404 — The requested file does not exist on the server. |
| 303 | Range Not Satisfiable | HTTP 416 — The server cannot fulfill the byte range request. The file may have changed. |
| 304 | Too Many Requests | HTTP 429 — Rate limited by the server. Try again later. |
| 305 | Server Error | HTTP 5xx — An error occurred on the server side. |
| 306 | Service Unavailable | HTTP 503 — The server is temporarily unavailable. |
| 307 | Redirect Loop | Too many HTTP redirects were followed. |
| 308 | Response Error | An unspecified HTTP response error. |
| 315 | Cloudflare Challenge | Cloudflare bot-protection detected on a 403/503/429 response. Import browser cookies to bypass — see the Browser Cookies guide. |
| Code | Name | Description |
|---|
| 400 | Disk Full | No space left on the target disk or storage quota exceeded. |
| 401 | Permission Denied | Insufficient permissions to write to the download directory. |
| Code | Name | Description |
|---|
| 500 | Metadata Failed | Failed to resolve torrent metadata from peers or trackers. |
| 501 | No Seeds | No seeders are available for this torrent. |
| 502 | Invalid Torrent File | The .torrent file is corrupt or not a valid BitTorrent metainfo file. |
| 503 | BitTorrent v2 Piece Layers Unavailable | A pure-v2 magnet resolved its info dict but no peer served the BEP 52 piece-layer hashes. The torrent cannot be verified until the layers are obtained — importing the .torrent file directly always works. |
| Code | Name | Description |
|---|
| 510 | Server Unreachable | Could not connect to the ED2K server. |
| 511 | File Not Found | The file was not found on the ED2K network. |
| Code | Name | Description |
|---|
| 520 | Parse Failed | Failed to parse the M3U8 playlist. The URL may not point to a valid HLS stream. |
| 521 | Segment Failed | One or more video segments failed to download. |
| 522 | Decrypt Failed | Failed to decrypt an encrypted HLS segment (AES-128). |
| Code | Name | Description |
|---|
| 530 | FTP Login Failed | Authentication failed. Check your username and password. |
| 531 | FTP File Not Found | The file does not exist on the FTP server. |
| 532 | FTP Transfer Failed | The file transfer was interrupted or failed. |
| 533 | SFTP Auth Failed | SFTP authentication failed. Check your credentials or private key. |
| 534 | SFTP Host Key Failed | The SFTP server's host key could not be verified, or the pinned fingerprint changed (TOFU). |
| Code | Name | Description |
|---|
| 540 | yt-dlp Not Found | The yt-dlp binary could not be located on PATH. Install yt-dlp to enable media downloads. |
| 541 | Authentication Required | The video requires login (sign-in, members-only, or age-restricted). Provide cookies via the cookies file option or a cookie header. |
| 542 | Format Unavailable | The format selector in media-format (aliases youtube-format, yt-format) did not match any of the formats yt-dlp returned. |
| Code | Name | Description |
|---|
| 900 | Engine Not Running | The download engine is not running. Try restarting the application. |
- 2xx Network errors: Check your internet connection, firewall, and DNS settings.
- 3xx HTTP errors: Verify the download URL is correct and accessible in a browser. For error 315 (Cloudflare Challenge), use the Browser Cookies guide to import credentials from an installed browser.
- 4xx File system errors: Ensure the download directory exists and has write permissions.
- 5xx Protocol errors: Check protocol-specific settings (trackers, credentials, etc.).
For detailed error information, check the application log files. The log directory is shown under Preferences > Advanced > App log path. Log files are rotated daily and named risuko.log.YYYY-MM-DD.