When Sonarr Hands Work to a Downloader

An approved Sonarr decision is not the same thing as a completed download. This chapter follows the moment a candidate crosses from Sonarr's policy engine into an external download client, focusing on client selection, fallback, rate limiting, status recording, and failure classification. The useful judgment is to ask two separate questions: did Sonarr decide to proceed, and did an external service successfully accept the work?

That distinction is easy to lose because the handoff may happen quickly. Sonarr has already parsed the release, mapped its episodes, and checked the library's policy. The next service call can still fail because the release disappeared, the chosen client is unavailable, credentials are rejected, or a transient request error interrupts communication. None of those outcomes necessarily means that the earlier policy decision was wrong.

Approval ends one responsibility and starts another

Before submission, Sonarr owns the candidate decision. It has a remote episode, a release report, and a result from the decision specifications. The download service receives that remote episode and selects a configured client. From this point, the client owns the mechanics of adding the release to its queue, while Sonarr remains responsible for choosing the boundary it calls and for recording what happened.

Client selection is constrained by the release's download protocol, the indexer that supplied it, the series' tags, and client availability. A torrent candidate should not be handed to a client that only supports the other protocol. A client associated with incompatible tags should not become an accidental route for the series. A client that has recently failed can be filtered from the available set. These are not new quality judgments; they are checks that the selected execution path can plausibly handle the already-approved candidate.

The service can also be given a specific client. When no specific client is required, it obtains the available clients for the protocol and tries them as distinct options. This is a useful separation between policy and execution. The policy engine can approve one release, while the download service chooses among several configured ways to carry out that approval.

The boundary has an important ownership rule: Sonarr publishes the episode-grabbed event only after a client accepts the release. It does not record a successful grab merely because the candidate passed its own rules. That ordering prevents the internal history from claiming that work exists when the external call never accepted it.

Fallback is bounded, not blind repetition

Suppose a release is eligible and two clients can handle its protocol. The first client may be unavailable or reject the request. Sonarr can try the next distinct configured client, recording which clients it has already attempted so the same operation is not sent repeatedly to the same failed boundary in one pass. If one client accepts the release, the service reports success and stops trying alternatives. If all available clients fail, the operation becomes a client-unavailability outcome rather than an endless loop.