fix: retry backoff for API calls and StatCard error state (#1568)

* fix: skip retry for client errors and add error state UI to StatCard

Query client now classifies gRPC status codes into retryable (server
errors, network failures) and non-retryable (client errors like
InvalidArgument, NotFound, PermissionDenied). Client errors are never
retried since they will not succeed. Server errors use exponential
backoff capped at 3 attempts.

StatCard displays an error icon with "Failed to load" message and an
optional retry button instead of the previous uninformative dash.

* test: align query-client retry count assertion with 3-attempt backoff

The shouldRetry implementation uses failureCount < 3, allowing up to 3
retries. The existing integration test expected only 2 retries (< 2).
Update to match the intended 3-attempt backoff behavior.

* fix: skip link wrapper on StatCard error state with onRetry

When both href and onRetry are set, the retry button was nested inside
a Link element creating invalid nested interactive controls. Skip the
link wrapper when rendering the error+retry state so the button
receives click events correctly.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/features/dashboard/pages/index.test.tsx

@@ -210,8 +210,8 @@ describe('DashboardPage', () => {
       expect(screen.getByText('7')).toBeInTheDocument()
     })
     expect(screen.getByText('3')).toBeInTheDocument()
-    // Error state shows dash
-    expect(screen.getByText('—')).toBeInTheDocument()
+    // Error state shows "Failed to load" with retry button
+    expect(screen.getByText('Failed to load')).toBeInTheDocument()
   })
 
   it('renders recent activity section', () => {

frontend/src/features/dashboard/pages/index.tsx

@@ -165,6 +165,7 @@ export function DashboardPage() {
           value={paymentsCount?.count}
           isLoading={paymentsQuery.isLoading}
           error={paymentsQuery.isError}
+          onRetry={() => void paymentsQuery.refetch()}
           showRecentQualifier={!!(paymentsCount?.isEstimate && !paymentsQuery.isLoading && !paymentsQuery.isError)}
           description="Active payment orders"
           icon={<CreditCard className="h-4 w-4" />}
@@ -175,6 +176,7 @@ export function DashboardPage() {
           value={bookingLogsCount?.count}
           isLoading={bookingLogsQuery.isLoading}
           error={bookingLogsQuery.isError}
+          onRetry={() => void bookingLogsQuery.refetch()}
           showRecentQualifier={!!(bookingLogsCount?.isEstimate && !bookingLogsQuery.isLoading && !bookingLogsQuery.isError)}
           description="Financial booking logs"
           icon={<FileText className="h-4 w-4" />}
@@ -185,6 +187,7 @@ export function DashboardPage() {
           value={ledgerPostingsCount?.count}
           isLoading={ledgerPostingsQuery.isLoading}
           error={ledgerPostingsQuery.isError}
+          onRetry={() => void ledgerPostingsQuery.refetch()}
           showRecentQualifier={!!(ledgerPostingsCount?.isEstimate && !ledgerPostingsQuery.isLoading && !ledgerPostingsQuery.isError)}
           description="Double-entry postings"
           icon={<BarChart3 className="h-4 w-4" />}

frontend/src/features/dashboard/pages/stat-card.test.tsx

@@ -1,5 +1,6 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { StatCard } from './stat-card'
 
 describe('StatCard', () => {
@@ -42,10 +43,39 @@ describe('StatCard', () => {
     expect(screen.getByText('Active accounts')).toBeInTheDocument()
   })
 
-  it('renders error state when error is true', () => {
+  it('renders error state with icon and message', () => {
     render(<StatCard title="Accounts" error />)
 
-    expect(screen.getByText('—')).toBeInTheDocument()
+    expect(screen.getByTestId('stat-card-error')).toBeInTheDocument()
+    expect(screen.getByText('Failed to load')).toBeInTheDocument()
+  })
+
+  it('renders retry button in error state when onRetry is provided', () => {
+    const onRetry = vi.fn()
+    render(<StatCard title="Accounts" error onRetry={onRetry} />)
+
+    expect(screen.getByRole('button', { name: /retry accounts/i })).toBeInTheDocument()
+  })
+
+  it('calls onRetry when retry button is clicked', async () => {
+    const user = userEvent.setup()
+    const onRetry = vi.fn()
+    render(<StatCard title="Accounts" error onRetry={onRetry} />)
+
+    await user.click(screen.getByRole('button', { name: /retry accounts/i }))
+    expect(onRetry).toHaveBeenCalledOnce()
+  })
+
+  it('does not render retry button when onRetry is not provided', () => {
+    render(<StatCard title="Accounts" error />)
+
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('hides description when in error state', () => {
+    render(<StatCard title="Accounts" error description="Active accounts" />)
+
+    expect(screen.queryByText('Active accounts')).not.toBeInTheDocument()
   })
 
   it('renders icon when provided', () => {

frontend/src/features/dashboard/pages/stat-card.tsx

@@ -1,6 +1,8 @@
 import { type ReactNode } from 'react'
 import { Link } from 'react-router-dom'
+import { AlertCircle, RefreshCw } from 'lucide-react'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Button } from '@/components/ui/button'
 import { cn } from '@/lib/utils'
 
 interface StatCardProps {
@@ -10,6 +12,7 @@ interface StatCardProps {
   icon?: ReactNode
   isLoading?: boolean
   error?: boolean
+  onRetry?: () => void
   showRecentQualifier?: boolean
   className?: string
   href?: string
@@ -22,6 +25,7 @@ export function StatCard({
   icon,
   isLoading,
   error,
+  onRetry,
   showRecentQualifier,
   className,
   href,
@@ -38,28 +42,41 @@ export function StatCard({
             data-testid="stat-card-skeleton"
             className="h-8 w-24 animate-pulse rounded bg-muted"
           />
+        ) : error ? (
+          <div data-testid="stat-card-error" className="flex items-center gap-2">
+            <AlertCircle className="h-4 w-4 text-destructive" />
+            <span className="text-sm text-muted-foreground">Failed to load</span>
+            {onRetry && (
+              <Button
+                variant="ghost"
+                size="sm"
+                className="ml-auto h-7 px-2"
+                onClick={(e) => {
+                  e.preventDefault()
+                  onRetry()
+                }}
+              >
+                <RefreshCw className="h-3 w-3" />
+                <span className="sr-only">Retry {title}</span>
+              </Button>
+            )}
+          </div>
         ) : (
           <div className="text-2xl font-bold">
-            {error ? (
-              <span className="text-muted-foreground">—</span>
-            ) : (
-              <>
-                {value ?? 0}
-                {showRecentQualifier && (
-                  <span className="ml-1 text-xs font-normal text-muted-foreground">recent</span>
-                )}
-              </>
+            {value ?? 0}
+            {showRecentQualifier && (
+              <span className="ml-1 text-xs font-normal text-muted-foreground">recent</span>
             )}
           </div>
         )}
-        {description && (
+        {description && !error && (
           <p className="mt-1 text-xs text-muted-foreground">{description}</p>
         )}
       </CardContent>
     </>
   )
 
-  if (href) {
+  if (href && !(error && onRetry)) {
     return (
       <Link to={href} className="block">
         <Card

frontend/src/lib/__tests__/query-client.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { ConnectError, Code } from '@connectrpc/connect'
+import { shouldRetry, retryDelay } from '../query-client'
+
+describe('shouldRetry', () => {
+  const nonRetryableCodes = [
+    Code.InvalidArgument,
+    Code.NotFound,
+    Code.AlreadyExists,
+    Code.PermissionDenied,
+    Code.Unauthenticated,
+    Code.FailedPrecondition,
+    Code.OutOfRange,
+    Code.Unimplemented,
+  ]
+
+  it.each(nonRetryableCodes)(
+    'does not retry ConnectError with code %s',
+    (code) => {
+      const error = new ConnectError('client error', code)
+      expect(shouldRetry(0, error)).toBe(false)
+    },
+  )
+
+  it('retries server errors (Internal)', () => {
+    const error = new ConnectError('server error', Code.Internal)
+    expect(shouldRetry(0, error)).toBe(true)
+    expect(shouldRetry(1, error)).toBe(true)
+    expect(shouldRetry(2, error)).toBe(true)
+  })
+
+  it('retries Unavailable errors', () => {
+    const error = new ConnectError('unavailable', Code.Unavailable)
+    expect(shouldRetry(0, error)).toBe(true)
+  })
+
+  it('stops retrying after 3 failures for server errors', () => {
+    const error = new ConnectError('server error', Code.Internal)
+    expect(shouldRetry(3, error)).toBe(false)
+  })
+
+  it('retries generic network errors', () => {
+    const error = new Error('Failed to fetch')
+    expect(shouldRetry(0, error)).toBe(true)
+    expect(shouldRetry(2, error)).toBe(true)
+  })
+
+  it('stops retrying generic errors after 3 failures', () => {
+    const error = new Error('Failed to fetch')
+    expect(shouldRetry(3, error)).toBe(false)
+  })
+})
+
+describe('retryDelay', () => {
+  it('uses exponential backoff', () => {
+    expect(retryDelay(0)).toBe(1000)
+    expect(retryDelay(1)).toBe(2000)
+    expect(retryDelay(2)).toBe(4000)
+  })
+
+  it('caps at 10 seconds', () => {
+    expect(retryDelay(5)).toBe(10_000)
+    expect(retryDelay(10)).toBe(10_000)
+  })
+})

frontend/src/lib/query-client.ts

@@ -1,18 +1,47 @@
 import { QueryClient } from '@tanstack/react-query'
 import { ConnectError, Code } from '@connectrpc/connect'
 
+/**
+ * gRPC/Connect status codes that correspond to client errors (4xx equivalent).
+ * These will not succeed on retry, so we skip them immediately.
+ */
+const NON_RETRYABLE_CODES: ReadonlySet<Code> = new Set([
+  Code.InvalidArgument,
+  Code.NotFound,
+  Code.AlreadyExists,
+  Code.PermissionDenied,
+  Code.Unauthenticated,
+  Code.FailedPrecondition,
+  Code.OutOfRange,
+  Code.Unimplemented,
+])
+
+/**
+ * Determines whether a failed query should be retried.
+ * - Client errors (4xx-equivalent gRPC codes) are never retried.
+ * - Server errors (5xx) and network failures retry up to 3 attempts.
+ */
+export function shouldRetry(failureCount: number, error: Error): boolean {
+  if (error instanceof ConnectError && NON_RETRYABLE_CODES.has(error.code)) {
+    return false
+  }
+  return failureCount < 3
+}
+
+/**
+ * Exponential backoff: 1s, 2s, 4s... capped at 10s.
+ */
+export function retryDelay(attempt: number): number {
+  return Math.min(1000 * 2 ** attempt, 10_000)
+}
+
 export const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       staleTime: 30_000,
       gcTime: 5 * 60 * 1000,
-      retry: (failureCount, error) => {
-        if (error instanceof ConnectError && error.code === Code.Unauthenticated) {
-          return false
-        }
-        return failureCount < 2
-      },
-      retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10_000),
+      retry: shouldRetry,
+      retryDelay,
       refetchOnWindowFocus: true,
       refetchOnReconnect: true,
     },

frontend/src/test/query-client.test.ts

@@ -22,10 +22,11 @@ describe('queryClient', () => {
     const options = queryClient.getDefaultOptions()
     const retry = options.queries?.retry as (failureCount: number, error: Error) => boolean
     expect(typeof retry).toBe('function')
-    // Regular errors retry up to 2 times
+    // Regular errors retry up to 3 times
     expect(retry(0, new Error('network'))).toBe(true)
     expect(retry(1, new Error('network'))).toBe(true)
-    expect(retry(2, new Error('network'))).toBe(false)
+    expect(retry(2, new Error('network'))).toBe(true)
+    expect(retry(3, new Error('network'))).toBe(false)
     // Unauthenticated errors should never retry
     expect(retry(0, new ConnectError('unauth', Code.Unauthenticated))).toBe(false)
   })