Radarr/Radarr · error · DownloadClientException

Freebox API returned error: {responseContent.GetErrorDescrip

Error message

Freebox API returned error: {responseContent.GetErrorDescription()}

What it means

Thrown when the Freebox API returns HTTP 200 OK but the JSON response body has Success == false. The Freebox API uses a two-layer protocol: HTTP status reflects transport success, while the JSON envelope's Success field reflects application-level success. This exception surfaces the Freebox error code/description from GetErrorDescription().

Source

Thrown at src/NzbDrone.Core/Download/Clients/FreeboxDownload/FreeboxDownloadProxy.cs:268

                throw new DownloadClientAuthenticationException(msg);
            }
            else if (response.StatusCode == HttpStatusCode.NotFound)
            {
                throw new FreeboxDownloadException("Unable to reach Freebox API. Verify 'API URL' setting for base URL and version.");
            }
            else if (response.StatusCode == HttpStatusCode.OK)
            {
                var responseContent = Json.Deserialize<FreeboxResponse<T>>(response.Content);

                if (responseContent.Success)
                {
                    return responseContent;
                }
                else
                {
                    var msg = $"Freebox API returned error: {responseContent.GetErrorDescription()}";
                    _logger.Error(msg);
                    throw new DownloadClientException(msg);
                }
            }
            else
            {
                throw new DownloadClientException("Unable to connect to Freebox, please check your settings.");
            }
        }
    }
}

View on GitHub (pinned to ca451608dc)

Solutions

Read the GetErrorDescription() value in the exception message — it contains the Freebox-specific error code and text that pinpoints the problem.
For download_dir errors, verify the destination directory exists on the Freebox and matches an allowed download path.
For duplicate task errors, check whether the same torrent/NZB is already in the Freebox download queue.
For disk errors, check available storage on the Freebox.
Retry with corrected parameters based on the specific Freebox error description.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before adding a task, validate the download directory exists on the Freebox
// (requires a prior successful GetDownloadConfiguration or filesystem check)
if (string.IsNullOrWhiteSpace(directory))
{
    _logger.Warn("Download directory is empty; Freebox may reject the task.");
}

Type guard

static bool IsFreeboxApiBusinessError(Exception ex) => ex is DownloadClientException dce && dce.Message.Contains("Freebox API returned error");

Try / catch

try
{
    _proxy.AddTaskFromUrl(url, directory, addPaused, addFirst, seedRatio, settings);
}
catch (DownloadClientException ex) when (ex.Message.Contains("Freebox API returned error"))
{
    // Parse the Freebox error description for specific handling
    _logger.Error(ex, "Freebox rejected the operation. Check error description for details.");
    // Optionally: re-throw as a user-facing message or retry with corrected params
}
catch (DownloadClientException ex)
{
    _logger.Error(ex, "Unexpected Freebox error.");
}

Prevention

Validate the download directory path against the Freebox's configured download directories before adding tasks.
Check for duplicate tasks before submitting — the Freebox will report an error for duplicates.
Ensure the Freebox has sufficient free disk space before large downloads.
Parse GetErrorDescription() output to surface actionable messages to the user.

When it happens

Trigger: ProcessRequest deserializes a FreeboxResponse<T> from a 200 response and responseContent.Success is false. Can occur on any API call: AddTaskFromUrl, AddTaskFromFile, DeleteTask, GetTasks, GetDownloadConfiguration, SetTorrentSettings.

Common situations: Adding a download with an invalid download_dir path, adding a duplicate task, the download URL is malformed or unreachable by the Freebox, disk full on the Freebox, or the requested operation conflicts with current task state (e.g., deleting a task that is mid-transfer).

Related errors

AI-assisted analysis of Radarr/Radarr@ca451608dc (2026-08-13). Data as JSON: /api/errors/47873e60dfc5e95b. Report an issue: GitHub.