Retry utilities with exponential backoff for handling transient failures.

This module provides retry logic for Fivetran API calls that may fail due to rate limiting, temporary server errors, or network issues. It implements exponential backoff with optional jitter to prevent thundering herd problems.

Quick Start

# Retry with defaults (3 attempts, exponential backoff)
{:ok, groups} = Fivetrex.Retry.with_backoff(fn ->
  Fivetrex.Groups.list(client)
end)

# Custom retry configuration
{:ok, connector} = Fivetrex.Retry.with_backoff(
  fn -> Fivetrex.Connectors.get(client, connector_id) end,
  max_attempts: 5,
  base_delay_ms: 500,
  max_delay_ms: 30_000
)

How It Works

1. Executes the provided function
2. If successful, returns the result immediately
3. If it fails with a retryable error, waits with exponential backoff
4. Repeats until success or max attempts reached

Retryable Errors

By default, these error types are retried:

• :rate_limited - Respects retry_after header when available
• :server_error - 5xx errors are typically transient

Non-retryable errors (returned immediately):

• :unauthorized - Invalid credentials won't become valid
• :not_found - Resource doesn't exist
• :unknown - Unexpected errors need investigation

Exponential Backoff

Delays increase exponentially: base_delay * 2^attempt

With default settings (base_delay: 1000ms):

• Attempt 1 fails → wait ~1 second
• Attempt 2 fails → wait ~2 seconds
• Attempt 3 fails → wait ~4 seconds
• (capped at max_delay)

Jitter

Optional random jitter prevents synchronized retries when multiple clients hit rate limits simultaneously:

Fivetrex.Retry.with_backoff(func, jitter: true)

Examples

Basic Usage

case Fivetrex.Retry.with_backoff(fn -> Fivetrex.Groups.list(client) end) do
  {:ok, %{items: groups}} ->
    process_groups(groups)

  {:error, error} ->
    # All retries exhausted
    Logger.error("Failed after retries: #{error.message}")
end

With Rate Limit Handling

# Respects Fivetran's retry-after header automatically
{:ok, _} = Fivetrex.Retry.with_backoff(fn ->
  Fivetrex.Connectors.sync(client, connector_id)
end)

Custom Retry Predicate

# Only retry on specific errors
Fivetrex.Retry.with_backoff(
  fn -> Fivetrex.Connectors.get(client, id) end,
  retry_if: fn
    %Fivetrex.Error{type: :rate_limited} -> true
    _ -> false
  end
)

Fire and Forget with Logging

Fivetrex.Retry.with_backoff(
  fn -> Fivetrex.Connectors.sync(client, connector_id) end,
  on_retry: fn error, attempt, delay ->
    Logger.warn("Retry #{attempt}: #{error.message}, waiting #{delay}ms")
  end
)