> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Retry Logic

> Handling network failures with exponential backoff

## Overview

The SDK includes built-in retry logic with exponential backoff. When a network request fails, it automatically retries with increasing delays, improving reliability in unstable network conditions.

## Default Behavior

By default, the SDK:

* Retries up to **2 times** on failure
* Uses **500ms** base backoff delay
* Doubles the delay after each retry (exponential backoff)

```
Attempt 1: Immediate
Attempt 2: Wait 500ms, then retry
Attempt 3: Wait 1000ms, then retry
→ Give up after 3 attempts
```

## Configuration

Customize retry behavior per trace:

```typescript theme={null}
const trace = client.trace({
  name: 'CriticalOperation',
  maxRetries: 5,        // Up to 5 retry attempts
  retryBackoff: 2000    // Start with 2 second delay
});
```

### Options

| Option         | Type     | Default | Description                |
| -------------- | -------- | ------- | -------------------------- |
| `maxRetries`   | `number` | `2`     | Maximum retry attempts     |
| `retryBackoff` | `number` | `500`   | Base delay in milliseconds |

## Exponential Backoff

The delay doubles after each failed attempt:

| Attempt | Delay (default) | Delay (2000ms base) |
| ------- | --------------- | ------------------- |
| 1       | 0ms (immediate) | 0ms                 |
| 2       | 500ms           | 2000ms              |
| 3       | 1000ms          | 4000ms              |
| 4       | 2000ms          | 8000ms              |
| 5       | 4000ms          | 16000ms             |

## Use Cases

### Critical Operations

For important data that must be delivered:

```typescript theme={null}
const trace = client.trace({
  name: 'PaymentConfirmation',
  maxRetries: 10,       // More retry attempts
  retryBackoff: 500     // Start with shorter delay
});
```

### Low-Priority Logging

For non-critical data where you want to fail fast:

```typescript theme={null}
const trace = client.trace({
  name: 'AnalyticsEvent',
  maxRetries: 1,        // Only one retry
  retryBackoff: 100     // Quick retry
});
```

### Disable Retries

Set `maxRetries: 0` to disable retry logic:

```typescript theme={null}
const trace = client.trace({
  name: 'NoRetry',
  maxRetries: 0  // Fail immediately on error
});
```

## Error Handling

The SDK handles retries silently - your code doesn't need to manage failures. However, if all retries are exhausted, the data is lost.

For critical operations, consider:

1. Using more retries
2. Implementing application-level backup
3. Monitoring for systematic failures

```typescript theme={null}
// Application-level fallback
const trace = client.trace({ name: 'CriticalData', maxRetries: 5 });

// Store locally as backup
try {
  localStorage.setItem('pendingTrace', JSON.stringify(traceData));
} catch (e) {
  // Handle storage errors
}

trace.addEvent('critical_event', traceData);
```

## v2 Resilience Improvements

SDK v2 includes several improvements for handling high-volume and unreliable network conditions.

### Flush Batching

Flush requests are batched — up to 100 items per flush. This reduces the number of network requests and improves throughput.

### Rate Limiting

The SDK includes built-in rate limiting to prevent overwhelming the gateway during bursts of activity.

### Keep-Alive Failure Handling

The keep-alive timer automatically stops after 3 consecutive failures, preventing wasted resources on dead connections. See [Traces](/concepts/traces) for details.

### Queue Management

Each trace has a configurable flush queue with a default maximum size of 4096 items. When the queue is full, new items are dropped and the `onDropped` callback is invoked:

```typescript theme={null}
const trace = client.trace({
  name: 'HighVolume',
  maxQueueSize: 8192,
  callbacks: {
    onDropped: (trace, reason) => console.warn('Dropped:', reason)
  }
});
```

## Network Conditions

The retry logic is especially useful for:

* **Mobile networks** - Intermittent connectivity
* **Slow connections** - Request timeouts
* **Server issues** - Temporary 5xx errors
* **Rate limiting** - Brief throttling periods

## Best Practices

### Match Retries to Importance

```typescript theme={null}
// Critical: payment confirmation
client.trace({ name: 'Payment', maxRetries: 10 });

// Important: user action
client.trace({ name: 'UserAction', maxRetries: 5 });

// Nice-to-have: analytics
client.trace({ name: 'Analytics', maxRetries: 2 });
```

### Consider Total Time

With exponential backoff, retries can take significant time:

| maxRetries | retryBackoff | Max Total Time |
| ---------- | ------------ | -------------- |
| 2          | 500ms        | \~1.5 seconds  |
| 5          | 500ms        | \~15.5 seconds |
| 5          | 1000ms       | \~31 seconds   |

### Don't Over-Retry

Excessive retries can:

* Block the flush queue
* Delay subsequent traces
* Waste bandwidth on permanent failures

## Next Steps

<CardGroup cols={2}>
  <Card title="TypeScript" icon="code" href="/advanced/typescript">
    Type-safe SDK usage
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/client">
    Complete API documentation
  </Card>
</CardGroup>