fix(youtube): a refused YouTube action answers a 422 that says what to do

The two manual syncs (subscriptions import, playlist pull) had no YouTubeError
handler, so a quota, token or transport failure was a raw 500 and the blocking
"Server error" dialog (E9 F1). The other YouTube routes answered either the
upstream's English or a playlist-scoped "youtube_failed".

One helper, routes/_common.youtube_refusal: 422 {code: "youtube", reason} with
the reason sorted by what the user can do — quota (wait for the reset),
reconnect (the token step refused), unavailable (retry). Used by every route
that surfaces a YouTube failure; localizeDetail translates it.

"Reconnect" had no path: a grant Google revoked still read as granted, so
Settings and the wizard offered no connect button while every call failed.
An invalid_grant from the token endpoint now clears the stored grant.

backend/app/routes/_common.py

@@ -13,6 +13,7 @@ from sqlalchemy.orm import Session
 
 from app.db import Base
 from app.models import User
+from app.youtube.client import YouTubeError, refusal_reason
 
 M = TypeVar("M", bound=Base)
 
@@ -51,3 +52,12 @@ def owned_or_404(
     if getattr(obj, owner_attr) != user.id:
         raise not_found(what)
     return obj
+
+
+def youtube_refusal(exc: YouTubeError) -> HTTPException:
+    """The answer to an action YouTube refused: a 422 whose reason the UI translates
+    (`errors.youtube.<reason>`). One definition, because the routes had grown three shapes of it —
+    a bare English string quoting the upstream message, a playlist-scoped reason, and nothing at
+    all (a raw 500 from the manual syncs). The upstream failure is already logged where it
+    happened (`youtube.api.error`)."""
+    return HTTPException(status_code=422, detail={"code": "youtube", "reason": refusal_reason(exc)})

backend/app/routes/channels.py

@@ -25,7 +25,7 @@ from app.models import (
     User,
     Video,
 )
-from app.routes._common import get_or_404, not_found, owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
@@ -424,7 +424,7 @@ def explore_channel(
                 channel = db.get(Channel, channel_id)
             result = explore_ingest_page(db, yt, channel, page_token)
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't load this channel: {exc}")
+        raise youtube_refusal(exc)
     return {
         "channel_id": channel_id,
         "ingested": result["ingested"],
@@ -583,9 +583,7 @@ def subscribe(
             if "subscriptionDuplicate" in exc.reason.split(","):
                 yt_sub_id = ""
             else:
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube couldn't subscribe you: {exc}"
-                )
+                raise youtube_refusal(exc)
         # Enrich a stub channel (title/thumbnail/subscriber count) so it shows up properly right
         # away, on BOTH the normal and the desync path — a resurfaced stub still needs metadata to
         # render. Keep the client open (we're still inside the `with`); a metadata failure here
@@ -649,7 +647,7 @@ def unsubscribe(
     except YouTubeError as exc:
         # 422 (a real, explainable error → speaking modal), not 502 which the client treats as
         # a transient "connection lost" gateway blip.
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't unsubscribe you: {exc}")
+        raise youtube_refusal(exc)
     db.delete(sub)
     db.commit()
     return {"unsubscribed": channel_id}

backend/app/routes/feed.py

@@ -29,7 +29,7 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.routes._common import get_or_404
+from app.routes._common import get_or_404, youtube_refusal
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
@@ -411,7 +411,7 @@ def get_video_detail(
         ):
             items = yt.get_videos([video_id])
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube lookup failed: {exc}")
+        raise youtube_refusal(exc)
     if not items:
         raise HTTPException(status_code=404, detail="Unknown video")
 

backend/app/routes/playlists.py

@@ -23,7 +23,7 @@ from app.sync.playlists import (
     sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import get_or_404, owned_or_404
+from app.routes._common import get_or_404, owned_or_404, youtube_refusal
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -322,8 +322,12 @@ def sync_youtube(
     if not has_read_scope(user):
         raise _refused(403, "youtube_read_scope")
     _check_pull_cooldown(user)
-    with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-        return sync_user_playlists(db, user)
+    try:
+        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+            return sync_user_playlists(db, user)
+    except YouTubeError as exc:
+        db.rollback()
+        raise youtube_refusal(exc)
 
 
 @router.post("/{playlist_id}/revert-youtube")
@@ -344,9 +348,9 @@ def revert_youtube(
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
             return repull_playlist(db, user, pl)
-    except YouTubeError:
+    except YouTubeError as exc:
         db.rollback()
-        raise _refused(422, "youtube_failed")
+        raise youtube_refusal(exc)
 
 
 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
@@ -371,8 +375,8 @@ def push_plan(
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             plan = plan_merge(db, user, pl)
-    except YouTubeError:
-        raise _refused(422, "youtube_failed")
+    except YouTubeError as exc:
+        raise youtube_refusal(exc)
     plan["remaining_today"] = quota.remaining_today(db)
     plan["affordable"] = plan["units_estimate"] <= plan["remaining_today"]
     return plan
@@ -404,9 +408,9 @@ def push(
             if plan["units_estimate"] > quota.remaining_today(db):
                 raise _refused(429, "quota_exceeded")
             return merge_playlist(db, user, pl, live=live)
-    except YouTubeError:
+    except YouTubeError as exc:
         db.rollback()
-        raise _refused(422, "youtube_failed")
+        raise youtube_refusal(exc)
 
 
 @router.get("/{playlist_id}")
@@ -496,8 +500,8 @@ def delete_playlist(
             with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
                 with YouTubeClient(db, user) as yt:
                     yt.delete_playlist(pl.yt_playlist_id)
-        except YouTubeError:
-            raise _refused(422, "youtube_failed")
+        except YouTubeError as exc:
+            raise youtube_refusal(exc)
     db.delete(pl)  # items cascade
     db.commit()
     return {"deleted": playlist_id}

backend/app/routes/sync.py

@@ -7,10 +7,12 @@ from app.audit import AuditAction
 from app.auth import admin_user, current_user, has_read_scope, require_human
 from app.db import get_db
 from app.models import Channel, Subscription, User, Video
+from app.routes._common import youtube_refusal
 from app.ratelimit import RateLimiter
 from app.sync.runner import estimate_deep_backfill
 from app.sync.subscriptions import import_subscriptions
 from app.scheduler import running_job_ids
+from app.youtube.client import YouTubeError
 
 router = APIRouter(prefix="/api/sync", tags=["sync"])
 
@@ -32,8 +34,14 @@ def sync_subscriptions(user: User = Depends(require_human), db: Session = Depend
         )
     if not _sync_limiter.allow(str(user.id)):
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
-    with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
-        result = import_subscriptions(db, user)
+    try:
+        with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
+            result = import_subscriptions(db, user)
+    except YouTubeError as exc:
+        # The onboarding wizard's first call: an unguarded failure here was a raw 500 and the
+        # blocking "Server error" dialog, with nothing the user could act on (E9 F1).
+        db.rollback()
+        raise youtube_refusal(exc)
     result["quota_used_estimate"] = m.used
     result["quota_remaining_today"] = m.remaining
     return result

backend/app/youtube/client.py

@@ -9,6 +9,7 @@ uses OAuth.
 import logging
 from collections.abc import Iterator
 from datetime import datetime, timedelta, timezone
+from typing import Literal
 
 import httpx
 
@@ -108,6 +109,22 @@ def is_quota_refusal(exc: YouTubeError) -> bool:
     return any(r in _QUOTA_REASONS for r in exc.reason.split(","))
 
 
+# What a refused YouTube action means to the person who asked for it — the three things they can
+# act on differently: wait for tomorrow's budget, reconnect the account, or try again later.
+YouTubeRefusal = Literal["quota", "reconnect", "unavailable"]
+
+
+def refusal_reason(exc: YouTubeError) -> YouTubeRefusal:
+    """Sort a failure by what the user can do about it. The token step failing (Google refused the
+    refresh, or there is no usable token at all — raised before any endpoint answered, so with no
+    path and no transport reason) means the account must be reconnected; retrying cannot help."""
+    if is_quota_refusal(exc):
+        return "quota"
+    if exc.path == "oauth2/token" or (not exc.path and exc.reason != "transport"):
+        return "reconnect"
+    return "unavailable"
+
+
 def _chunks(items: list, size: int) -> Iterator[list]:
     for i in range(0, len(items), size):
         yield items[i : i + size]
@@ -181,7 +198,10 @@ class YouTubeClient:
             },
         )
         if resp.status_code != 200:
-            raise _upstream_failure("POST", "oauth2/token", resp)
+            exc = _upstream_failure("POST", "oauth2/token", resp)
+            if exc.reason == "invalid_grant":
+                self._drop_dead_grant(tok)
+            raise exc
         data = resp.json()
         access = data["access_token"]
         tok.access_token = encrypt(access)
@@ -191,6 +211,25 @@ class YouTubeClient:
         log.info("Refreshed access token for user %s", self.user.id)
         return access
 
+    def _drop_dead_grant(self, tok) -> None:
+        """Google answered the refresh with `invalid_grant`: the grant was revoked or expired, and no
+        retry will revive it. Forget it, so the account reads as NOT connected — Settings and the
+        onboarding wizard then offer the connect button again (a fresh consent issues a new refresh
+        token). Kept as "granted", the UI showed a live connection with no way to renew it while
+        every call failed. Committed like the refresh above: the caller rolls back on the error."""
+        tok.scopes = None
+        tok.access_token = None
+        tok.refresh_token_enc = None
+        tok.expiry = None
+        self.db.add(tok)
+        self.db.commit()
+        # INFO: the refusal itself is already the warning (`youtube.api.error`, invalid_grant).
+        log.info(
+            "cleared the dead YouTube grant of user %s",
+            self.user.id,
+            extra=logs.event("youtube.grant.cleared"),
+        )
+
     # --- core request ---
     def _get(
         self,