Retries + Timeouts

Timeouts

SDKs support configuring connection and request timeouts:

TypeScript
Go
Rust

const client = new S2({
	accessToken: token,
	connectionTimeoutMillis: 3000,
	requestTimeoutMillis: 5000,
});

client := s2.New(token, &s2.ClientOptions{
	ConnectionTimeout: 5 * time.Second,
	RequestTimeout:    30 * time.Second,
})

let client = S2::new(
    S2Config::new(token)
        .with_connection_timeout(Duration::from_secs(5))
        .with_request_timeout(Duration::from_secs(10)),
)?;

Connection timeout: Maximum time to wait for a TCP connection to be established. This is a “fail fast” timeout that aborts slow connections early.
Request timeout: Maximum time to wait for a unary (non-streaming) request to complete. For append sessions, this value is also used to determine the SDK-enforced timeout for an individual batch append to be acknowledged.

Retry Behavior

SDKs automatically retry transient failures using exponential backoff with jitter.

TypeScript
Go
Rust

const client = new S2({
	accessToken: token,
	retry: {
		maxAttempts: 5,
		minBaseDelayMillis: 100,
		maxBaseDelayMillis: 2000,
	},
});

client := s2.New(token, &s2.ClientOptions{
	RetryConfig: &s2.RetryConfig{
		MaxAttempts:  5,
		MinBaseDelay: 100 * time.Millisecond,
		MaxBaseDelay: 2 * time.Second,
	},
})

let client = S2::new(
    S2Config::new(token).with_retry(
        RetryConfig::new()
            .with_max_attempts(NonZeroU32::new(5).unwrap())
            .with_min_base_delay(Duration::from_millis(100))
            .with_max_base_delay(Duration::from_secs(2)),
    ),
)?;

Append Retry Policy

Retrying appends requires care: if an append succeeds but the acknowledgement is lost (e.g., due to a network timeout), retrying would create duplicate records in a stream. The appendRetryPolicy setting controls how to react in this situation, by treating append retries as a special case.

Policy	Behavior
`all` (default)	Retry all failed appends. Duplicates are possible.
`noSideEffects`	Only retry append failures which could not have had a side effect.

Using noSideEffects means that, in the event of a failure, the caller will manually need to verify whether or not the append succeeded (e.g., by reading or otherwise inspecting the state of the stream).

To achieve “exactly-once” semantics in single-writer setups, a matchSeqNum precondition can be used when appending. See concurrency controls for details.For multiple-writer setups, a caller can use an idempotency key for later deduplication. This is touched upon in this blog post.

Configuration Reference

Timeout Settings

Setting	Default	Description
Connection timeout	3 seconds	Max time to establish TCP connection
Request timeout	5 seconds	Max time for request completion

Retry Settings

Setting	Default	Description
Max attempts	3	Maximum retry attempts
Min base delay	100 ms	Minimum base delay for exponential backoff
Max base delay	1 second	Maximum base delay (actual delay with jitter can be up to 2x)
Append retry policy	`all`	How to handle append retries when duplication is possible

SDKs

​Timeouts

​Retry Behavior

​Append Retry Policy

​Configuration Reference

​Timeout Settings

​Retry Settings

Timeouts

Retry Behavior

Append Retry Policy

Configuration Reference

Timeout Settings

Retry Settings