Skip to content

[Enhancement] Add configurable retry with exponential backoff for REST API calls #773

Description

@deepgram-robot

Summary

Add built-in retry logic with configurable exponential backoff for Deepgram REST API calls (pre-recorded transcription, TTS, Audio Intelligence), automatically retrying on transient errors (429, 500, 502, 503) with jitter.

Problem it solves

Developers building production audio processing pipelines need retry logic to handle transient API failures — rate limits during batch transcription, temporary server errors during peak load, or network hiccups. Currently, every Python SDK user must implement their own retry wrapper around Deepgram calls, leading to inconsistent retry strategies and missed edge cases (like respecting Retry-After headers or adding jitter to prevent thundering herd). Built-in retry with sensible defaults is table-stakes for production SDKs.

Proposed API

from deepgram import DeepgramClient, RetryConfig

# Configure retry behavior
client = DeepgramClient(
    api_key="...",
    retry=RetryConfig(
        max_retries=3,                     # Default: 3
        backoff_factor=0.5,                # 0.5s, 1s, 2s
        retry_on=[429, 500, 502, 503],     # Default retryable codes
        respect_retry_after=True,          # Use Retry-After header when present
    )
)

# Disable retries explicitly
client = DeepgramClient(api_key="...", retry=False)

# Default behavior (backward compatible): no retries
client = DeepgramClient(api_key="...")

Acceptance criteria

  • Configurable max retries, backoff factor, and retryable status codes
  • Respects Retry-After response header when present (overrides calculated backoff)
  • Adds jitter to backoff to prevent thundering herd
  • Does NOT retry on 4xx errors (except 429) by default
  • Retries are opt-in with sensible defaults to maintain backward compatibility
  • Works for all REST operations (transcription, TTS, intelligence, management)
  • Documented with usage example
  • Compatible with existing API

Raised by the DX intelligence system.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions