Retry and Timeout

AxilJS provides retry and timeout utilities through @axiljs/circuit for handling transient failures and preventing long-running operations from blocking an application indefinitely.

Use retry() when an operation may succeed after a temporary failure. Use withTimeout() when an asynchronous operation must complete within a defined time limit.

Retry with Backoff#

The retry() utility executes an asynchronous operation multiple times when it fails.

import { retry } from '@axiljs/circuit'
 
const data = await retry(
  () => fetchAPI(),
  {
    attempts: 3,
    delay: 1000,
    backoff: 'exponential'
  }
)

The retry configuration in this example includes:

• attempts — maximum number of attempts.
• delay — initial delay between retry attempts, in milliseconds.
• backoff — controls how the delay changes between attempts.

With backoff: 'exponential', the delay increases between subsequent retry attempts.

This is useful for transient failures such as temporary network errors or unavailable remote services.

Retry Workflow#

A retry operation can be represented as:

Operation
    │
    ▼
 Execute
    │
 ┌──┴───────────┐
 │              │
Success       Failure
 │              │
 ▼              ▼
Return       Wait
               │
               ▼
          Retry Attempt
               │
               ▼
            Execute

For example, a request configured with three attempts can retry a failed operation instead of immediately returning the initial failure.

Exponential Backoff#

Exponential backoff increases the waiting period between retry attempts.

const data = await retry(
  () => fetchAPI(),
  {
    attempts: 3,
    delay: 1000,
    backoff: 'exponential'
  }
)

This strategy is useful when communicating with remote services because repeatedly retrying a failed request immediately can increase load on an already unhealthy dependency.

Timeout#

Use withTimeout() to limit how long an asynchronous operation can run.

import { withTimeout } from '@axiljs/circuit'
 
const result = await withTimeout(
  fetch(url),
  5000,
  'Request timed out'
)

The second argument specifies the timeout duration in milliseconds.

In this example:

5000 ms = 5 seconds

If the operation does not complete within the configured timeout, the provided timeout message is used.

Combining Retry and Timeout#

Retry and timeout address different failure conditions.

Retry handles operations that fail and may succeed when attempted again. Timeout limits operations that take too long to complete.

They can therefore be used together when an application needs both retry behavior and execution time limits.

Request
  │
  ▼
Timeout Protection
  │
  ├──► Success
  │
  └──► Failure / Timeout
          │
          ▼
       Retry Policy
          │
          ▼
      Next Attempt

This combination is particularly useful for network requests and other remote service calls where both transient failures and excessive latency are possible.

Common Use Cases#

AxilJS retry and timeout utilities are useful for:

• External API requests
• Network operations
• Microservice calls
• Database operations
• Third-party integrations
• Transient service failures
• Preventing indefinitely hanging requests

For remote dependencies, retry policies should be configured carefully so that retries do not amplify load during an existing service outage.