Expired auth token throws into React 18 Suspense ErrorBoundary with no cache invalidation or retry API

Answer

When a protected fetch fails with a 401/403 because the bearer token has expired, React 18 Suspense simply throws that error to the nearest ErrorBoundary. Suspense itself does not know that the failure is transient, nor does it expose a public API to clear or refresh a cached entry. The only way to recover is to let the ErrorBoundary perform a token‑refresh, then force Suspense to re‑execute the data‑fetching thunk.

Modeling the Expiry inside an ErrorBoundary

• Throw a custom error. Wrap your fetch logic so that a 401/403 results in throw new AuthExpiredError('Token expired');. This separates recoverable auth errors from permanent ones.
• Catch the error. In a class ErrorBoundary, implement componentDidCatch(error) and check error instanceof AuthExpiredError. In a functional boundary, use useErrorBoundary or the onReset pattern.
• Refresh the token. Call your refresh endpoint, update the global auth context or state, and then trigger a re‑render that will re‑execute the thunk.
• Re‑run the fetch. Because the thunk is a function that reads the current token at call time, a new render will call it again with the refreshed token.

Invalidating the Suspense Cache

Suspense caches by the thunk’s identity and its arguments. There is no API to delete a specific entry, so you must change the key that the thunk uses:

1. Key rotation. Add a tokenVersion or timestamp argument to the thunk. Store the current version in context; increment it after a successful refresh. The thunk signature becomes const fetchData = (v) => fetch('/data', {headers:{Authorization:`Bearer ${getToken(v)}`}});. When tokenVersion changes, Suspense treats it as a new key and starts a fresh fetch.
2. Component remount. Wrap the Suspense subtree in a component whose key is tied to the token version. Changing the key unmounts the subtree, clearing Suspense’s internal cache for that branch. This is heavier but guarantees a clean slate.

Should @tanstack/react-query Own the Flow?

For production‑grade authentication, @tanstack/react-query is a better fit. It provides explicit query keys, manual invalidation (queryClient.invalidateQueries), and retry hooks. A typical pattern is:

const queryFn = async () => {
  try { return await fetchWithAuth(); }
  catch (e) {
    if (isTokenExpired(e)) {
      await refreshToken();
      return await fetchWithAuth();
    }
    throw e;
  }
};

useQuery(['data', tokenVersion], queryFn, { suspense: true });

React‑Query will automatically refetch after tokenVersion changes and will not serve stale data.

Missing Diagnostic Detail

Do you currently use a class ErrorBoundary with componentDidCatch or the React 19 onReset hook? The exact pattern determines how you trigger the re‑render that re‑executes the thunk.