diff --git a/tests/tools/test_spotify_client.py b/tests/tools/test_spotify_client.py
index d22bc448039..d43fe9d535e 100644
--- a/tests/tools/test_spotify_client.py
+++ b/tests/tools/test_spotify_client.py
@@ -4,6 +4,7 @@ import json
 
 import pytest
 
+from hermes_cli.auth import AuthError
 from plugins.spotify import client as spotify_mod
 from plugins.spotify import tools as spotify_tool
 
@@ -297,3 +298,25 @@ def test_spotify_playback_recently_played_action(monkeypatch: pytest.MonkeyPatch
     payload = json.loads(spotify_tool._handle_spotify_playback({"action": "recently_played", "limit": 5}))
     assert seen and seen[0]["limit"] == 5
     assert isinstance(payload, dict)
+
+
+def test_client_wraps_invalid_grant_as_spotify_auth_required_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """SpotifyClient._resolve_runtime wraps AuthError(code=spotify_refresh_invalid_grant) into SpotifyAuthRequiredError."""
+
+    def _raise_invalid_grant(**kwargs):
+        raise AuthError(
+            "Spotify refresh token has expired or was revoked. Run `hermes auth spotify` again.",
+            provider="spotify",
+            code="spotify_refresh_invalid_grant",
+            relogin_required=True,
+        )
+
+    monkeypatch.setattr(
+        spotify_mod,
+        "resolve_spotify_runtime_credentials",
+        _raise_invalid_grant,
+    )
+    with pytest.raises(spotify_mod.SpotifyAuthRequiredError, match="expired or was revoked"):
+        spotify_mod.SpotifyClient()
diff --git a/website/docs/user-guide/features/spotify.md b/website/docs/user-guide/features/spotify.md
index e9b8f3748a1..1a2b628293a 100644
--- a/website/docs/user-guide/features/spotify.md
+++ b/website/docs/user-guide/features/spotify.md
@@ -1,6 +1,6 @@
 # Spotify
 
-Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth. Tokens are stored in `~/.hermes/auth.json` and refreshed automatically on 401; you only log in once per machine.
+Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth. Tokens are stored in `~/.hermes/auth.json` and refreshed automatically on 401; you only log in once per machine (refresh tokens expire after ~6 months; re-run `hermes auth spotify` when they do).
 
 Unlike Hermes' built-in OAuth integrations (Google, GitHub Copilot, Codex), Spotify requires every user to register their own lightweight developer app. Spotify does not let third parties ship a public OAuth app that anyone can use. It takes about two minutes and `hermes auth spotify` walks you through it.