Global error handling: persistent UI states + readable messages across all pages

Infrastructure:
- lib/apiError.ts: shared apiErrorMessage() extracts FastAPI detail from
  axios responses, falls back to err.message, then a readable fallback string
- components/PageError.tsx: reusable full-page error with WifiOff icon +
  Retry button, styled for both light and dark mode

Pages fixed (initial data load):
- revenue, relationships, knowledge, sequences, quotes, crm: add loadError
  state; on load failure show <PageError> with retry instead of disappearing
  toast leaving user looking at blank page
- billing, actions, settings: SWR hooks already carry error state; now render
  <PageError> instead of silently rendering broken UI

All mutation catches across 8 pages now use apiErrorMessage() so backend
validation messages (e.g. "Product unavailable", "Invalid token") surface
directly instead of generic "Failed to X"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Sai Sridhar

frontend/components/PageError.tsx

@@ -0,0 +1,27 @@
+import { WifiOff, RefreshCw } from 'lucide-react';
+
+interface PageErrorProps {
+  message?: string;
+  onRetry?: () => void;
+}
+
+export default function PageError({ message = 'Failed to load data', onRetry }: PageErrorProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-24 text-center">
+      <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-red-50 dark:bg-red-900/10 border border-red-100 dark:border-red-900/30 mb-4">
+        <WifiOff className="h-6 w-6 text-red-400" />
+      </div>
+      <p className="font-semibold text-gray-900 dark:text-gray-100 mb-1">{message}</p>
+      <p className="text-sm text-gray-500 dark:text-gray-400 mb-5">Check your connection or try again.</p>
+      {onRetry && (
+        <button
+          onClick={onRetry}
+          className="inline-flex items-center gap-2 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-750 transition-colors shadow-sm"
+        >
+          <RefreshCw className="h-4 w-4" />
+          Retry
+        </button>
+      )}
+    </div>
+  );
+}

frontend/lib/apiError.ts

@@ -0,0 +1,9 @@
+export function apiErrorMessage(err: unknown, fallback = 'Something went wrong. Please try again.'): string {
+  if (err && typeof err === 'object' && 'response' in err) {
+    const res = (err as { response?: { data?: { detail?: string; message?: string } } }).response;
+    if (res?.data?.detail) return res.data.detail;
+    if (res?.data?.message) return res.data.message;
+  }
+  if (err instanceof Error) return err.message;
+  return fallback;
+}

frontend/pages/actions/index.tsx

@@ -10,8 +10,10 @@ import CreateTaskModal from '@/components/CreateTaskModal';
 import TaskDetailModal from '@/components/TaskDetailModal';
 import LoadingSpinner from '@/components/LoadingSpinner';
 import EmptyState from '@/components/EmptyState';
+import PageError from '@/components/PageError';
 import { useActions } from '@/lib/hooks';
 import { actionsApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { Action, ActionPriority } from '@/lib/types';
 import clsx from 'clsx';
 
@@ -33,7 +35,7 @@ export default function ActionsPage() {
     if (!sessionLoading && !session) router.replace('/auth/signin');
   }, [session, sessionLoading, router]);
 
-  const { data, isLoading } = useActions({});
+  const { data, isLoading, error: actionsError, mutate: reloadActions } = useActions({});
 
   useEffect(() => {
     if (data) setActions(data);
@@ -47,26 +49,31 @@ export default function ActionsPage() {
         deadline: updated.deadline,
       });
       setActions((prev) => prev.map((a) => (a.id === result.id ? { ...a, ...result } : a)));
-    } catch {
-      toast.error('Failed to update task');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Failed to update task'));
     }
   };
 
   const handleDelete = async (id: string) => {
     try {
       await actionsApi.deleteAction(id);
       setActions((prev) => prev.filter((a) => a.id !== id));
-    } catch {
-      toast.error('Failed to delete task');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Failed to delete task'));
     }
   };
 
   const handleCreate = (action: Action) => {
     setActions((prev) => [action, ...prev]);
   };
 
-  if (sessionLoading) return <LoadingSpinner fullPage />;
+  if (sessionLoading || isLoading) return <LoadingSpinner fullPage />;
   if (!session) return null;
+  if (actionsError) return (
+    <Layout title="Actions">
+      <PageError message="Couldn't load actions" onRetry={() => reloadActions()} />
+    </Layout>
+  );
 
   // Filter by priority
   const filtered =

frontend/pages/billing/index.tsx

@@ -16,8 +16,10 @@ import {
 import toast from 'react-hot-toast';
 import Layout from '@/components/Layout';
 import LoadingSpinner from '@/components/LoadingSpinner';
+import PageError from '@/components/PageError';
 import { useBillingStatus } from '@/lib/hooks';
 import { billingApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { PlanId, Plan } from '@/lib/types';
 import clsx from 'clsx';
 
@@ -120,6 +122,11 @@ export default function BillingPage() {
 
   if (sessionLoading || billingLoading) return <LoadingSpinner fullPage />;
   if (!session) return null;
+  if (billingError) return (
+    <Layout title="Billing">
+      <PageError message="Couldn't load billing status" onRetry={() => window.location.reload()} />
+    </Layout>
+  );
 
   const handleUpgrade = async (planId: PlanId) => {
     if (planId === 'free') return;
@@ -128,9 +135,7 @@ export default function BillingPage() {
       const { checkout_url } = await billingApi.createCheckoutSession(planId, 'monthly');
       window.location.href = checkout_url;
     } catch (err: unknown) {
-      const detail =
-        (err as { response?: { data?: { detail?: string } } })?.response?.data?.detail;
-      const msg = detail || (err instanceof Error ? err.message : 'Failed to start checkout. Please try again.');
+      const msg = apiErrorMessage(err, 'Failed to start checkout. Please try again.');
       setCheckoutError(msg);
       toast.error(msg, { duration: 8000 });
       console.error('[checkout]', err);

frontend/pages/crm/index.tsx

@@ -20,7 +20,9 @@ import {
 import { formatDistanceToNow } from 'date-fns';
 import clsx from 'clsx';
 import Layout from '@/components/Layout';
+import PageError from '@/components/PageError';
 import { contactsApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { ContactProfile, ContactDetail } from '@/lib/types';
 import toast from 'react-hot-toast';
 
@@ -683,6 +685,7 @@ export default function CRMPage() {
   const [activeTab, setActiveTab] = useState<'contacts' | 'pipeline'>('contacts');
   const [contacts, setContacts] = useState<ContactProfile[]>([]);
   const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState(false);
   const [search, setSearch] = useState('');
   const [selectedContact, setSelectedContact] = useState<ContactDetail | null>(null);
   const [detailLoading, setDetailLoading] = useState(false);
@@ -697,8 +700,9 @@ export default function CRMPage() {
       setLoading(true);
       const data = await contactsApi.getContacts(q || undefined);
       setContacts(data);
-    } catch {
-      toast.error('Failed to load contacts');
+    } catch (err) {
+      setLoadError(true);
+      toast.error(apiErrorMessage(err, 'Failed to load contacts'));
     } finally {
       setLoading(false);
     }
@@ -724,8 +728,8 @@ export default function CRMPage() {
     try {
       const detail = await contactsApi.getContact(contact.email);
       setSelectedContact(detail);
-    } catch {
-      toast.error('Failed to load contact details');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Failed to load contact details'));
       setActiveProfile(null);
     } finally {
       setDetailLoading(false);
@@ -739,6 +743,11 @@ export default function CRMPage() {
   }, []);
 
   if (sessionLoading) return null;
+  if (loadError && contacts.length === 0 && !search) return (
+    <Layout title="CRM">
+      <PageError message="Couldn't load contacts" onRetry={() => { setLoadError(false); loadContacts(); }} />
+    </Layout>
+  );
 
   return (
     <>

frontend/pages/knowledge/index.tsx

@@ -6,7 +6,9 @@ import { BookOpen, Search, Zap, Trash2, Loader2, Tag } from 'lucide-react';
 import toast from 'react-hot-toast';
 import Layout from '@/components/Layout';
 import LoadingSpinner from '@/components/LoadingSpinner';
+import PageError from '@/components/PageError';
 import { knowledgeApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { KnowledgeEntry } from '@/lib/types';
 
 const TYPE_COLORS: Record<string, string> = {
@@ -26,6 +28,7 @@ export default function KnowledgePage() {
   const { session, isLoading: sessionLoading } = useSessionContext();
   const [entries, setEntries] = useState<KnowledgeEntry[]>([]);
   const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState(false);
   const [extracting, setExtracting] = useState(false);
   const [query, setQuery] = useState('');
   const [typeFilter, setTypeFilter] = useState('');
@@ -40,8 +43,9 @@ export default function KnowledgePage() {
     try {
       const data = await knowledgeApi.getAll(q || undefined, type || undefined);
       setEntries(data.entries || []);
-    } catch {
-      toast.error('Failed to load knowledge base');
+    } catch (err) {
+      setLoadError(true);
+      toast.error(apiErrorMessage(err, 'Failed to load knowledge base'));
     } finally {
       setLoading(false);
     }
@@ -60,8 +64,8 @@ export default function KnowledgePage() {
       const result = await knowledgeApi.bulkExtract();
       toast.success(`Extracted ${result.extracted} knowledge entries`);
       await load(query, typeFilter);
-    } catch {
-      toast.error('Extraction failed');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Extraction failed'));
     } finally {
       setExtracting(false);
     }
@@ -72,14 +76,19 @@ export default function KnowledgePage() {
     try {
       await knowledgeApi.delete(id);
       setEntries(prev => prev.filter(e => e.id !== id));
-    } catch {
-      toast.error('Delete failed');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Delete failed'));
     } finally {
       setDeletingId(null);
     }
   };
 
   if (sessionLoading || !session) return <LoadingSpinner fullPage />;
+  if (loadError && entries.length === 0 && !query && !typeFilter) return (
+    <Layout title="Knowledge Base">
+      <PageError message="Couldn't load knowledge base" onRetry={() => { setLoadError(false); load(); }} />
+    </Layout>
+  );
 
   return (
     <>

frontend/pages/quotes/index.tsx

@@ -7,7 +7,9 @@ import { formatDistanceToNow } from 'date-fns';
 import toast from 'react-hot-toast';
 import Layout from '@/components/Layout';
 import LoadingSpinner from '@/components/LoadingSpinner';
+import PageError from '@/components/PageError';
 import { quotesApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { Quote } from '@/lib/types';
 
 const STATUS_STYLES: Record<string, string> = {
@@ -103,6 +105,7 @@ export default function QuotesPage() {
   const { session, isLoading: sessionLoading } = useSessionContext();
   const [quotes, setQuotes] = useState<Quote[]>([]);
   const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState(false);
   const [statusFilter, setStatusFilter] = useState('');
 
   useEffect(() => {
@@ -113,8 +116,9 @@ export default function QuotesPage() {
     try {
       const data = await quotesApi.getAll();
       setQuotes(data.quotes || []);
-    } catch {
-      toast.error('Failed to load quotes');
+    } catch (err) {
+      setLoadError(true);
+      toast.error(apiErrorMessage(err, 'Failed to load quotes'));
     } finally {
       setLoading(false);
     }
@@ -127,12 +131,17 @@ export default function QuotesPage() {
       await quotesApi.updateStatus(id, status);
       await load();
       toast.success(`Quote marked as ${status}`);
-    } catch {
-      toast.error('Update failed');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Update failed'));
     }
   };
 
   if (sessionLoading || !session) return <LoadingSpinner fullPage />;
+  if (loadError && quotes.length === 0) return (
+    <Layout title="Quotes">
+      <PageError message="Couldn't load quotes" onRetry={() => { setLoadError(false); load(); }} />
+    </Layout>
+  );
 
   const filtered = statusFilter ? quotes.filter(q => q.status === statusFilter) : quotes;
   const totalPipeline = quotes.filter(q => q.status !== 'rejected').reduce((s, q) => s + q.total, 0);

frontend/pages/relationships/index.tsx

@@ -7,7 +7,9 @@ import { formatDistanceToNow } from 'date-fns';
 import toast from 'react-hot-toast';
 import Layout from '@/components/Layout';
 import LoadingSpinner from '@/components/LoadingSpinner';
+import PageError from '@/components/PageError';
 import { relationshipsApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { RelationshipContact } from '@/lib/types';
 
 const HEALTH_COLORS = {
@@ -35,6 +37,7 @@ export default function RelationshipsPage() {
   const { session, isLoading: sessionLoading } = useSessionContext();
   const [contacts, setContacts] = useState<RelationshipContact[]>([]);
   const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState(false);
   const [refreshing, setRefreshing] = useState(false);
   const [filter, setFilter] = useState<'all' | 'at_risk' | 'alert'>('all');
 
@@ -46,8 +49,9 @@ export default function RelationshipsPage() {
     try {
       const data = await relationshipsApi.getAll();
       setContacts(data.contacts || []);
-    } catch {
-      toast.error('Failed to load relationships');
+    } catch (err) {
+      setLoadError(true);
+      toast.error(apiErrorMessage(err, 'Failed to load relationships'));
     } finally {
       setLoading(false);
     }
@@ -62,6 +66,11 @@ export default function RelationshipsPage() {
   };
 
   if (sessionLoading || !session) return <LoadingSpinner fullPage />;
+  if (loadError && contacts.length === 0) return (
+    <Layout title="Relationships">
+      <PageError message="Couldn't load relationships" onRetry={() => { setLoadError(false); load(); }} />
+    </Layout>
+  );
 
   const filtered = contacts.filter(c => {
     if (filter === 'at_risk') return c.health_label === 'at_risk';

frontend/pages/revenue/index.tsx

@@ -6,7 +6,9 @@ import { DollarSign, AlertTriangle, RefreshCw, Loader2, Check, X, Zap } from 'lu
 import toast from 'react-hot-toast';
 import Layout from '@/components/Layout';
 import LoadingSpinner from '@/components/LoadingSpinner';
+import PageError from '@/components/PageError';
 import { revenueApi } from '@/lib/api';
+import { apiErrorMessage } from '@/lib/apiError';
 import type { RevenueSummary, RevenueSignal } from '@/lib/types';
 
 const TYPE_COLORS: Record<string, string> = {
@@ -35,6 +37,7 @@ export default function RevenuePage() {
   const { session, isLoading: sessionLoading } = useSessionContext();
   const [summary, setSummary] = useState<RevenueSummary | null>(null);
   const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState(false);
   const [scanning, setScanning] = useState(false);
   const [updatingId, setUpdatingId] = useState<string | null>(null);
 
@@ -46,8 +49,9 @@ export default function RevenuePage() {
     try {
       const data = await revenueApi.getSummary();
       setSummary(data);
-    } catch {
-      toast.error('Failed to load revenue data');
+    } catch (err) {
+      setLoadError(true);
+      toast.error(apiErrorMessage(err, 'Failed to load revenue data'));
     } finally {
       setLoading(false);
     }
@@ -61,8 +65,8 @@ export default function RevenuePage() {
       const result = await revenueApi.scan();
       toast.success(`Found ${result.signals_found} new signals`);
       await load();
-    } catch {
-      toast.error('Scan failed');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Scan failed'));
     } finally {
       setScanning(false);
     }
@@ -73,14 +77,19 @@ export default function RevenuePage() {
     try {
       await revenueApi.updateSignal(signal.id, status);
       await load();
-    } catch {
-      toast.error('Update failed');
+    } catch (err) {
+      toast.error(apiErrorMessage(err, 'Update failed'));
     } finally {
       setUpdatingId(null);
     }
   };
 
   if (sessionLoading || !session) return <LoadingSpinner fullPage />;
+  if (loadError && !summary) return (
+    <Layout title="Revenue Signals">
+      <PageError message="Couldn't load revenue data" onRetry={() => { setLoadError(false); load(); }} />
+    </Layout>
+  );
 
   return (
     <>