Retries & fallbacks

Retry or fallback?

A retry asks the same provider to perform the same operation again. A fallback routes the operation to another implementation. These decisions have different correctness, privacy, and billing consequences; configure them separately.

Set a recovery budget

type RecoveryPolicy = {
  maxAttempts: number; // Includes the initial request
  deadlineMs: number;  // Covers the whole operation
  maxEstimatedCostUsd: number;
  approvedProviderIds: readonly string[];
};

const searchPolicy: RecoveryPolicy = {
  maxAttempts: 2,
  deadlineMs: 4_000,
  maxEstimatedCostUsd: 0.01, // Application budget, not provider pricing
  approvedProviderIds: ['primary-search'],
};

Before every attempt, check remaining time, attempts, estimated cost, and approval for the provider. Use bounded backoff with jitter where appropriate. Understand the native SDK's retry behavior so your application loop does not multiply retries underneath it.

Protect side effects

A timed-out request may have completed upstream. For email, payments, or writes, avoid inferring failure from a lost response. Use the provider's documented idempotency mechanism when available and persist the logical operation identifier before retrying.

Resend's idempotency guide documents its key behavior. A key at one provider does not deduplicate work at another provider; cross-provider delivery needs an application-owned reconciliation strategy.

Respect data boundaries

A secondary provider is another destination for your data. Approve it before an outage, including retention, region, contractual constraints, and the exact payload it may receive. Redacting logs does not prevent sensitive input from being sent upstream.

• Fallback must satisfy the original capability requirements.
• Return provider provenance when it affects interpretation of results.
• Record each attempt without copying secrets or full payloads into telemetry.
• If recovery is exhausted, return a clear failure rather than a fabricated success.