Skip to content

[Enhancement] Add automatic reconnection with exponential backoff for streaming sessions #739

Description

@deepgram-robot

Summary

Add built-in automatic reconnection with configurable exponential backoff to the streaming WebSocket clients (ListenWebSocketClient, AsyncListenWebSocketClient), enabling production-grade resilience without requiring developers to implement their own reconnection logic.

Problem it solves

Production streaming applications face network interruptions, transient API errors, and connection timeouts. Currently, developers must implement their own reconnection logic around the SDK's WebSocket clients — handling backoff timing, connection state management, re-authentication, and gap detection. This is complex, error-prone, and the #1 source of production issues reported in SDK issues. A built-in reconnection mechanism with sensible defaults would dramatically reduce the barrier to production deployment.

Proposed API

from deepgram import DeepgramClient, LiveOptions, ReconnectionConfig

client = DeepgramClient()

# Configure reconnection behavior
reconnect_config = ReconnectionConfig(
    enabled=True,                    # default: False (opt-in)
    max_retries=10,                  # default: 5, 0 = unlimited
    initial_delay_ms=500,            # default: 1000
    max_delay_ms=30000,              # default: 30000
    backoff_multiplier=2.0,          # default: 2.0
    jitter=True,                     # default: True (prevents thundering herd)
)

connection = client.listen.live.v("1")
connection.configure_reconnection(reconnect_config)

# Events fire on reconnection lifecycle
connection.on(LiveTranscriptionEvents.Reconnecting, on_reconnecting)
connection.on(LiveTranscriptionEvents.Reconnected, on_reconnected)
connection.on(LiveTranscriptionEvents.ReconnectFailed, on_reconnect_failed)

connection.start(LiveOptions(model="nova-3", language="en"))

Acceptance criteria

  • Reconnection is opt-in (disabled by default for backward compatibility)
  • Supports configurable exponential backoff with jitter
  • Emits lifecycle events: Reconnecting, Reconnected, ReconnectFailed
  • Re-establishes connection with same options (model, language, encoding)
  • Works with both sync and async WebSocket clients
  • Stops retrying after max_retries and emits final failure event
  • Documented with usage example
  • Compatible with existing API (non-breaking addition)

Raised by the DX intelligence system.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions