fixes and improvements

backend/src/media_library_viewer_api/dependencies.py

@@ -12,7 +12,7 @@ import logging
 from functools import lru_cache
 from typing import Any
 
-from fastapi import Request
+from fastapi import HTTPException, Request
 
 from media_library_viewer_api.clients.jellyfin import JellyfinClient
 from media_library_viewer_api.clients.jellyseerr import JellyseerrClient
@@ -82,6 +82,27 @@ def _ssh_client_for(cache_key: tuple[str, str, str, int, str, str | None, str |
     )
     try:
         client.connect()
+    except RuntimeError as exc:
+        message = str(exc)
+        lowered = message.lower()
+        logger.exception("Failed to establish SSH connection to %s", host or "<unset>")
+        if "banner" in lowered:
+            raise HTTPException(
+                status_code=502,
+                detail=(
+                    f"SSH banner not received from {host}:{port}. "
+                    "Confirm the host, port, and firewall; the backend could not complete the SSH handshake."
+                ),
+            ) from exc
+        if "authentication failed" in lowered or "no authentication methods available" in lowered:
+            raise HTTPException(
+                status_code=401,
+                detail=(
+                    f"SSH authentication failed for {host}:{port}. "
+                    "Check the selected key, passphrase, username, or password."
+                ),
+            ) from exc
+        raise HTTPException(status_code=502, detail=message) from exc
     except Exception:
         logger.exception("Failed to establish SSH connection to %s", host or "<unset>")
         raise