handling-authentication-errors

Handling Authentication Errors

Apps need two related but distinct patterns:

1. Platform app token (fbsfeaturetoken / x-app-feature-token) — AppTokenValidationError on Gate/Dashboard proxy calls.
2. App-owned session (httpOnly cookie, e.g. app_session) — backend /api/account/me (or equivalent) on load.

Do not treat every failed fetch as “logged out”. That lies to the user when the backend is restarting (deploy), the proxy returns 502, or the network blips.

---

Session probe invariant (backend SaaS apps)

Any SPA that boots auth from GET /api/account/me (or similar) MUST follow this table:

Response on session check	Meaning	UI action
401	Session rejected by backend	Show login / anon state
403 with known business code (membership_revoked, tenant_suspended, …)	Authenticated but blocked	Dedicated blocked screen
Everything else (502/503/504, 5xx, network error, timeout, aborted)	No verdict — server may be down	Retry (see below), then “Can't reach server” + Try again. Do not clear session cookie or force login

A timeout on the first call after idle or deploy is a cold start, not a logout. Retry once with the full deadline, then report "Can't reach server" — never clear the session. Timeout sizing: skill app-backend § Cold Starts (Scale-to-Zero).

Anti-pattern (never ship)

// BAD — treats deploy blip as logout
catch (e) {
  if (e.code !== 'tenant_suspended' && e.code !== 'membership_revoked') {
    setAuth({ status: 'anon' }) // ← 502 during fusebase deploy looks like logout
  }
}

Required pattern

type SessionVerdict = 'authenticated' | 'anon' | 'blocked' | 'unknown'

async function probeSession(): Promise<SessionVerdict> {
  const res = await fetch('/api/account/me', { credentials: 'include' })
  if (res.status === 401) return 'anon'
  if (res.status === 403) {
    const body = await res.json().catch(() => ({}))
    if (body.code === 'membership_revoked' || body.code === 'tenant_suspended') return 'blocked'
    return 'unknown' // do not assume logout
  }
  if (!res.ok) return 'unknown'
  return 'authenticated'
}

async function probeSessionWithDeployTolerance(): Promise<SessionVerdict> {
  const delays = [0, 400, 1200] // ms — survives fusebase deploy pod restart window
  let last: SessionVerdict = 'unknown'
  for (const ms of delays) {
    if (ms) await new Promise((r) => setTimeout(r, ms))
    try {
      const v = await probeSession()
      if (v !== 'unknown') return v
      last = v
    } catch {
      last = 'unknown'
    }
  }
  return last
}