Retry

Retry System

The Retry System handles failed operations with intelligent retry strategies.

Core Concepts

Error Classification

Errors are classified into categories:

Class	Description
`network`	Connection failures
`timeout`	Request timeouts
`server`	5xx errors
`client`	4xx errors
`abort`	Cancelled requests
`unknown`	Unclassified errors

Backoff Strategies

Strategy	Behavior
`exponential`	Delay doubles each attempt
`linear`	Delay increases linearly
`constant`	Fixed delay

Usage

Configure Retry Count

QueryEngine for Query Retries

Query-level retry is available via QueryEngine.executeQuery(). QueryClient.fetchQuery() does not support retry configuration.

import { QueryEngine } from '@soulcache/core/query';
 
const engine = new QueryEngine({
  staleTime: 5000,
});
 
// Queries via QueryEngine get automatic retry
const data = await engine.executeQuery({
  queryKey: ['flaky-api'],
  queryFn: async (signal) => {
    const res = await fetch('/api/flaky', { signal });
    return res.json();
  },
  retry: { maxRetries: 3, baseDelay: 1000 },
});

Mutation Retry

Use MutationEntry.mutateWithRetry() for automatic retry on mutations:

const entry = client.getMutationCache().create({
  mutationId: 'mut-1',
  mutationFn: async (vars) => {
    const res = await fetch('/api/data', { method: 'POST', body: JSON.stringify(vars) });
    return res.json();
  },
});
 
// Retries up to 3 times with 1000ms delay
const data = await entry.mutateWithRetry({ name: 'John' }, 3, 1000);

Jitter

Jitter is enabled by default to prevent thundering herd. It adds 0-50% random delay to retry timing.

Best Practices

Retry Guidelines

Classify errors correctly — Different errors need different strategies
Use exponential backoff — Prevents overwhelming the server
Add jitter — Prevents thundering herd
Set reasonable retries — Don't retry forever
Handle final failure — Always handle exhausted retries

Retry

On this page