Skip to main content

​
Overview

The SDK supports automatic retries with exponential backoff for transient errors. Retries are enabled by default.

​
Default Behavior

By default, the SDK automatically retries failed requests that are likely to succeed on retry, such as:
  • Rate limit errors (429)
  • Server errors (500, 502, 503, 504)
  • Network connection failures

​
Per-Request Configuration

Override retry behavior for a single API call: 
const result = await factify.documents.list(
  { pageSize: 10 },
  {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  }
);

​
Global Configuration

Override retry behavior for all operations at SDK initialization: 
const factify = new Factify({
  bearerAuth: process.env.FACTIFY_KEY,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,    // Start with 1ms delay
      maxInterval: 50,       // Cap at 50ms delay
      exponent: 1.1,         // Exponential growth factor
      maxElapsedTime: 100,   // Give up after 100ms total
    },
    retryConnectionErrors: false,
  },
});

​
Configuration Options

OptionTypeDescription
strategy"backoff"Retry strategy to use
backoff.initialIntervalnumberInitial delay in milliseconds
backoff.maxIntervalnumberMaximum delay between retries
backoff.exponentnumberExponential backoff multiplier
backoff.maxElapsedTimenumberMaximum total retry time
retryConnectionErrorsbooleanWhether to retry on connection failures

​
How Exponential Backoff Works

With exponential backoff, the delay between retries increases with each attempt: 
Attempt 1: initialInterval * (exponent ^ 0) = 1ms
Attempt 2: initialInterval * (exponent ^ 1) = 1.1ms
Attempt 3: initialInterval * (exponent ^ 2) = 1.21ms
...continues until maxInterval or maxElapsedTime is reached

​
Disabling Retries

To disable retries entirely for a specific request: 
const result = await factify.documents.list(
  { pageSize: 10 },
  {
    retries: {
      strategy: "backoff",
      backoff: {
        maxElapsedTime: 0,  // No retries
      },
    },
  }
);

​
Best Practices

  1. Use defaults for most cases - The SDK’s default retry behavior works well for typical use cases
  2. Increase timeouts for batch operations - When processing many items, allow more retry time
  3. Disable retries for time-sensitive operations - If you need immediate feedback, consider disabling retries
  4. Monitor retry patterns - If you see many retries, consider reducing request volume