fix(dashboard): differentiate API error states — offline, timeout, server, unauthorized (#3373) (#3395)

- Add getErrorVariant() utility that maps errors to ErrorState variants:
  - No statusCode + 'Failed to fetch' → offline
  - No statusCode + 'timeout'/'AbortError' → timeout
  - 403 → unauthorized
  - 429 → rate-limited
  - 404 → not-found
  - 5xx → server-5xx
- AnalyticsPage: replace inline error div with ErrorState + retry button
- MetricsPage: replace inline error div with ErrorState + retry button
- ErrorState: add role='alert' for a11y compliance

All 1300 tests pass. TypeScript strict clean.

Author: OneStepAt4time

dashboard/src/components/ErrorState.tsx

@@ -82,6 +82,7 @@ export function ErrorState({ variant, message, onRetry }: ErrorStateProps): Reac
     <div
       className="flex flex-col items-center justify-center gap-4 py-16 px-6 text-center"
       data-testid="error-state"
+      role="alert"
       data-variant={variant}
     >
       <div className="rounded-full border border-[var(--color-void-lighter)] bg-[var(--color-surface)] p-4">

dashboard/src/pages/AnalyticsPage.tsx

@@ -28,6 +28,8 @@ import { ModelDistributionBar } from '../components/analytics/ModelDistributionB
 import { getAnalyticsSummary, getRateLimitAnalytics } from '../api/client';
 import { formatCurrency } from '../utils/formatNumber';
 import { formatDateShort } from '../utils/formatDate';
+import { ErrorState } from '../components/ErrorState';
+import { getErrorVariant } from '../utils/getErrorVariant';
 import type { AnalyticsSummary, RateLimitAnalyticsResponse } from '../types';
 import { RateLimitChart } from '../components/analytics/RateLimitChart';
 import { RateLimitForecastCard } from '../components/analytics/RateLimitForecastCard';
@@ -85,7 +87,7 @@ export default function AnalyticsPage() {
   const t = useT();
   const [data, setData] = useState<AnalyticsSummary | null>(null);
   const [rateLimitData, setRateLimitData] = useState<RateLimitAnalyticsResponse | null>(null);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<{ raw: unknown; message: string } | null>(null);
   const [loading, setLoading] = useState(true);
 
   const fetchData = useCallback(async () => {
@@ -98,11 +100,11 @@ export default function AnalyticsPage() {
         setData(summary.value);
         setError(null);
       } else {
-        setError(summary.reason instanceof Error ? summary.reason.message : t('analytics.loadError'));
+        setError({ raw: summary.reason, message: summary.reason instanceof Error ? summary.reason.message : t('analytics.loadError') });
       }
       if (rateLimits.status === 'fulfilled') setRateLimitData(rateLimits.value);
     } catch (e) {
-      setError(e instanceof Error ? e.message : t('analytics.loadError'));
+      setError({ raw: e, message: e instanceof Error ? e.message : t('analytics.loadError') });
     } finally {
       setLoading(false);
     }
@@ -123,9 +125,11 @@ export default function AnalyticsPage() {
 
   if (error) {
     return (
-      <div className="rounded-lg border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-400" role="alert">
-        Failed to load analytics: {error}
-      </div>
+      <ErrorState
+        variant={getErrorVariant(error.raw)}
+        message={error.message}
+        onRetry={() => { void fetchData(); }}
+      />
     );
   }
 

dashboard/src/pages/MetricsPage.tsx

@@ -23,6 +23,8 @@ import { formatDateShort } from '../utils/formatDate';
 import { downloadCSV } from '../utils/csv-export';
 import { ChartFrame } from '../components/shared/ChartFrame';
 import { sanitizeErrorMessage } from '../utils/sanitizeErrorMessage';
+import { ErrorState } from '../components/ErrorState';
+import { getErrorVariant } from '../utils/getErrorVariant';
 
 type RangePreset = '7d' | '30d' | '90d';
 type Granularity = 'day' | 'hour' | 'key';
@@ -77,7 +79,7 @@ function generateCSV(data: AggregateMetricsResponse): string {
 export default function MetricsPage() {
   const t = useT();
   const [data, setData] = useState<AggregateMetricsResponse | null>(null);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState<{ raw: unknown; message: string } | null>(null);
   const [range, setRange] = useState<RangePreset>('7d');
   const [granularity, setGranularity] = useState<Granularity>('day');
   const sseConnected = useStore((s) => s.sseConnected);
@@ -90,7 +92,7 @@ export default function MetricsPage() {
       const result = await getMetricsAggregate({ from, to: now.toISOString(), groupBy: granularity });
       setData(result);
     } catch (err) {
-      setError(sanitizeErrorMessage(err, t('metrics.loadError')));
+      setError({ raw: err, message: sanitizeErrorMessage(err, t('metrics.loadError')) });
     }
   }, [range, granularity]);
 
@@ -177,9 +179,11 @@ export default function MetricsPage() {
 
       {/* Error state */}
       {error && (
-        <div className="rounded-lg border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-300" role="alert">
-          {error}
-        </div>
+        <ErrorState
+          variant={getErrorVariant(error.raw)}
+          message={error.message}
+          onRetry={() => { void fetchData(); }}
+        />
       )}
 
       {/* Summary cards */}

dashboard/src/utils/getErrorVariant.ts

@@ -0,0 +1,78 @@
+/**
+ * utils/getErrorVariant.ts — Map API/network errors to ErrorState variant.
+ *
+ * The API client (api/client.ts) attaches `statusCode` to thrown errors.
+ * Network failures throw plain Error without statusCode.
+ * This utility maps both patterns to the correct ErrorState variant.
+ */
+
+import type { ErrorVariant } from '../components/ErrorState';
+
+interface ApiError extends Error {
+  statusCode?: number;
+}
+
+/**
+ * Map an error to the appropriate ErrorState variant.
+ *
+ * - No statusCode + "Failed to fetch" → offline
+ * - No statusCode + "timeout" / "AbortError" → timeout
+ * - 403 → unauthorized
+ * - 429 → rate-limited
+ * - 404 → not-found
+ * - 5xx → server-5xx
+ * - Other → server-5xx (safe default)
+ */
+export function getErrorVariant(error: unknown): ErrorVariant {
+  const err = error as ApiError;
+
+  // Network errors (no statusCode)
+  if (!err?.statusCode) {
+    const msg = (err?.message ?? '').toLowerCase();
+
+    if (msg.includes('failed to fetch') || msg.includes('network') || msg.includes('net::')) {
+      return 'offline';
+    }
+
+    if (msg.includes('timeout') || msg.includes('timed out') || msg.includes('abort')) {
+      return 'timeout';
+    }
+
+    // Unknown error without status code — assume server issue
+    return 'server-5xx';
+  }
+
+  // HTTP status code based mapping
+  const status = err.statusCode;
+
+  if (status === 403) return 'unauthorized';
+  if (status === 404) return 'not-found';
+  if (status === 429) return 'rate-limited';
+  if (status >= 500) return 'server-5xx';
+
+  // 4xx other than 403/404/429 — treat as server error for UX
+  return 'server-5xx';
+}
+
+/**
+ * Get a human-readable error message from an API error.
+ * Uses sanitizeErrorMessage for technical error cleanup.
+ */
+export function getUserErrorMessage(error: unknown, fallback?: string): string {
+  const err = error as ApiError;
+  const raw = err?.message ?? '';
+
+  // Network errors
+  if (!err?.statusCode) {
+    const msg = raw.toLowerCase();
+    if (msg.includes('failed to fetch') || msg.includes('network')) {
+      return 'Unable to reach the Aegis server. Check your connection.';
+    }
+    if (msg.includes('timeout') || msg.includes('timed out')) {
+      return 'The request timed out. The server may be under load.';
+    }
+  }
+
+  // For status-coded errors, use the raw message (already sanitized by API client)
+  return raw || fallback || 'Something went wrong. Please try again.';
+}