Retry Logic

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:

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:

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:

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

Disable Retries

Set maxRetries: 0 to disable retry logic:

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:

Using more retries
Implementing application-level backup
Monitoring for systematic failures

// 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 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:

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

// 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

TypeScript

Type-safe SDK usage

API Reference

Complete API documentation

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Default Behavior

Configuration

Options

Exponential Backoff

Use Cases

Critical Operations

Low-Priority Logging

Disable Retries

Error Handling

v2 Resilience Improvements

Flush Batching

Rate Limiting

Keep-Alive Failure Handling

Queue Management

Network Conditions

Best Practices

Match Retries to Importance

Consider Total Time

Don’t Over-Retry

Next Steps

TypeScript

API Reference

​Overview

​Default Behavior

​Configuration

​Options

​Exponential Backoff

​Use Cases

​Critical Operations

​Low-Priority Logging

​Disable Retries

​Error Handling

​v2 Resilience Improvements

​Flush Batching

​Rate Limiting

​Keep-Alive Failure Handling

​Queue Management

​Network Conditions

​Best Practices

​Match Retries to Importance

​Consider Total Time

​Don’t Over-Retry

​Next Steps

TypeScript

API Reference

Overview

Default Behavior

Configuration

Options

Exponential Backoff

Use Cases

Critical Operations

Low-Priority Logging

Disable Retries

Error Handling

v2 Resilience Improvements

Flush Batching

Rate Limiting

Keep-Alive Failure Handling

Queue Management

Network Conditions

Best Practices

Match Retries to Importance

Consider Total Time

Don’t Over-Retry

Next Steps