fix(connectors): narrow broad except in tokens.py 401-handling (No-Silent-Fallbacks)

[itomek]

Why

PR #1599 (#1592) added 401-handling in _refresh_token (src/gaia/connectors/tokens.py, ~lines 214–216) that parses the OAuth error payload with a broad swallow:

try:
    err_payload = response.json()
except Exception:
    err_payload = {}

This violates CLAUDE.md's "No Silent Fallbacks" rule (a handler that discards the error and returns a placeholder). If response.json() raises something unexpected (e.g. an AttributeError on a mock, or a non-JSON body throwing something other than a decode error), the payload silently collapses to {} and the user-facing message at tokens.py:231 always reports invalid_client — hiding the real cause.

Flagged in the PR #1599 review (github-actions bot) but the PR merged before it was addressed, so the violation is now in main.

Fix

Narrow the handler — httpx's .json() only raises json.JSONDecodeError (a ValueError subclass) on a malformed body, so this is sufficient and lets any genuine programming error surface:

try:
    err_payload = response.json()
except (ValueError, json.JSONDecodeError):
    err_payload = {}

(Confirm json is imported in tokens.py.)

Related

• [Bug]: Agent UI — connected Google account can't be used by Email Triage agent (per-agent grant missing in UI, then token 401) #1592 / PR fix(connectors): repair Email Triage Google grant + actionable token errors (#1592) #1599 (merged) — introduced the 401-handling block.

[github-actions]

Confirmed — valid catch. The broad except Exception at src/gaia/connectors/tokens.py:214-216 does swallow non-decode errors and collapse the payload to {}, which then masks the real OAuth error behind the default invalid_client message at line 231.

Two notes for whoever picks this up:

🟡 The same pattern is a few lines up in the 400 block (tokens.py:189-192) — identical try: response.json() / except Exception: payload = {}. Worth fixing both in the same change so the file is clean rather than leaving a matching violation behind.

🟢 json doesn't need to be imported. httpx's .json() raises json.JSONDecodeError, which is a subclass of ValueError, so except ValueError: alone is sufficient and keeps the import list untouched:

try:
    err_payload = response.json()
except ValueError:
    err_payload = {}

That narrows to malformed-body only and lets a genuine programming error (e.g. an AttributeError on a mock) surface loudly, per the No-Silent-Fallbacks rule.

Good first-issue sized — happy to point a contributor at it.