fix: use smart retry that skips 4xx errors but retries server/network errors

Client errors (4xx) won't resolve on retry, so skip them. Server errors
(5xx) and network failures get up to 3 retries with React Query's
default exponential backoff.

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

Author: arbrandes

src/data/hooks/queryHooks.test.tsx

@@ -40,6 +40,7 @@ const createWrapper = (queryClient?: QueryClient) => {
     defaultOptions: {
       queries: {
         retry: false,
+        retryDelay: 0,
         gcTime: 0,
       },
       mutations: {
@@ -96,12 +97,14 @@ describe('queryHooks', () => {
           throw new Error('Function not implemented.');
         },
       });
-      (api.initializeList as jest.Mock).mockRejectedValue(new Error('API Error'));
+      const error: any = new Error('API Error');
+      error.response = { status: 403 };
+      (api.initializeList as jest.Mock).mockRejectedValue(error);
 
       // Don't use gcTime: 0 here — we need the seeded cache entry to persist
       // for the fallback lookup via queryClient.getQueryData()
       const queryClient = new QueryClient({
-        defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+        defaultOptions: { queries: { retry: false, retryDelay: 0 }, mutations: { retry: false } },
       });
       queryClient.setQueryData(
         learnerDashboardQueryKeys.initialize(undefined),
@@ -120,6 +123,48 @@ describe('queryHooks', () => {
       expect(result.current.data).toEqual(mockNormalUserData);
     });
 
+    it('should not retry on 4xx errors', async () => {
+      mockUseMasquerade.mockReturnValue({
+        masqueradeUser: null,
+        setMasqueradeUser(): void { throw new Error('Function not implemented.'); },
+      });
+      const error: any = new Error('Forbidden');
+      error.response = { status: 403 };
+      (api.initializeList as jest.Mock).mockRejectedValue(error);
+
+      const { result } = renderHook(() => useInitializeLearnerHome(), {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true);
+      });
+
+      // 4xx errors should not be retried — only 1 call
+      expect(api.initializeList).toHaveBeenCalledTimes(1);
+    });
+
+    it('should retry on 5xx errors up to 3 times', async () => {
+      mockUseMasquerade.mockReturnValue({
+        masqueradeUser: null,
+        setMasqueradeUser(): void { throw new Error('Function not implemented.'); },
+      });
+      const error: any = new Error('Server Error');
+      error.response = { status: 500 };
+      (api.initializeList as jest.Mock).mockRejectedValue(error);
+
+      const { result } = renderHook(() => useInitializeLearnerHome(), {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true);
+      });
+
+      // 1 initial + 3 retries = 4 total calls
+      expect(api.initializeList).toHaveBeenCalledTimes(4);
+    });
+
     it('should have correct query configuration for masquerading', async () => {
       const masqueradeUser = 'test-user';
       mockUseMasquerade.mockReturnValue({

src/data/hooks/queryHooks.ts

@@ -23,7 +23,11 @@ const useInitializeLearnerHome = () => {
       };
     },
     staleTime: 5 * 60 * 1000, // 5 minutes — dashboard data rarely changes while viewing
-    retry: false,
+    retry: (failureCount, error: any) => {
+      // Don't retry client errors (4xx) — they won't resolve on retry
+      if (error?.response?.status >= 400 && error?.response?.status < 500) return false;
+      return failureCount < 3;
+    },
     retryOnMount: !masqueradeUser,
     refetchOnMount: !masqueradeUser,
   });