Retry Configuration

Overview

Cuey automatically retries failed webhook deliveries with configurable retry logic. You can customize the number of retries, backoff delay, and backoff strategy.

RetryConfig Structure

The retry configuration consists of three parameters:

{
  "maxRetries": 3,
  "backoffMs": 1000,
  "backoffType": "exponential"
}

Parameters

maxRetries: Maximum number of retry attempts (1-10). Defaults to 3 if not specified.
backoffMs: Initial backoff delay in milliseconds before the first retry (100-5000). Defaults to 500 if not specified.
backoffType: Backoff strategy. Options: exponential (backoff doubles each retry) or linear (constant backoff). Defaults to exponential if not specified.

Retry Behavior

When a webhook fails (non-2xx status code or network error):

A new retry event is created
The retry event inherits the original event’s configuration
The retry event is scheduled with the configured backoff delay
The process repeats until maxRetries is reached or the webhook succeeds

Backoff Strategies

Exponential Backoff

The delay increases exponentially with each retry:

Retry 1: backoffMs * 2^0 = backoffMs
Retry 2: backoffMs * 2^1 = backoffMs * 2
Retry 3: backoffMs * 2^2 = backoffMs * 4

Example Configuration:

{
  "maxRetries": 3,
  "backoffMs": 1000,
  "backoffType": "exponential"
}

This results in:

Retry 1: 1 second delay
Retry 2: 2 seconds delay
Retry 3: 4 seconds delay

Linear Backoff

The delay remains constant for each retry:

Retry 1: backoffMs
Retry 2: backoffMs
Retry 3: backoffMs

Example Configuration:

{
  "maxRetries": 3,
  "backoffMs": 2000,
  "backoffType": "linear"
}

This results in:

Retry 1: 2 seconds delay
Retry 2: 2 seconds delay
Retry 3: 2 seconds delay

Default Configuration

If you don’t specify retry_config, Cuey uses these defaults:

{
  "maxRetries": 3,
  "backoffMs": 500,
  "backoffType": "exponential"
}

Configuration Examples

Quick Retries (Transient Errors)

For transient errors that resolve quickly:

{
  "maxRetries": 5,
  "backoffMs": 500,
  "backoffType": "exponential"
}

Aggressive Retries (Critical Operations)

For critical operations that must succeed:

{
  "maxRetries": 10,
  "backoffMs": 1000,
  "backoffType": "exponential"
}

Slow Retries (Rate-Limited APIs)

For APIs that may be rate-limited:

{
  "maxRetries": 3,
  "backoffMs": 5000,
  "backoffType": "linear"
}

No Retries

To disable retries, set maxRetries to 1:

{
  "maxRetries": 1,
  "backoffMs": 1000,
  "backoffType": "linear"
}

Retry Event Tracking

Retry events are linked to the original event via the retry_of field. You can:

Track all retry attempts for a specific original event
Query events with a specific retry_of value to see all retry attempts
Understand the relationship between the original event and its retries

Best Practices

Choose Appropriate maxRetries

✅ Good: maxRetries: 3 - Most errors resolve in 3 attempts
❌ Avoid: maxRetries: 10 - May waste resources on permanent failures

Use Exponential Backoff for Most Cases

✅ Good: Exponential backoff (default) - Reduces load on failing endpoints
✅ Good: Linear for specific cases - When consistent delay is needed (e.g., rate-limited APIs)

Consider API Rate Limits

For rate-limited APIs, use longer delays with linear backoff:

{
  "maxRetries": 3,
  "backoffMs": 5000,
  "backoffType": "linear"
}

Monitor Retry Patterns

Track retry success rates to optimize configuration. Monitor:

Failed events (status: "failed")
Response status codes
Error messages
Retry success rates

Retry Event Lifecycle

Original Event Fails: Event status changes to failed
Retry Event Created: New event created with retry_of pointing to original
Retry Scheduled: Retry event scheduled with backoff delay
Retry Executed: Retry event attempts webhook delivery
Success or Next Retry: If successful, process ends. If failed, create next retry

Configuration Limits

Parameter	Minimum	Maximum	Default
`maxRetries`	1	10	3
`backoffMs`	100	5000	500

Retrying Events

Learn how retries work.

TypeScript SDK

Get started with the TypeScript SDK.

REST API

Explore the REST API documentation.

Core Concepts

Configuration

​Overview

​RetryConfig Structure

​Parameters

​Retry Behavior

​Backoff Strategies

​Exponential Backoff

​Linear Backoff

​Default Configuration

​Configuration Examples

​Quick Retries (Transient Errors)

​Aggressive Retries (Critical Operations)

​Slow Retries (Rate-Limited APIs)

​No Retries

​Retry Event Tracking

​Best Practices

​Choose Appropriate maxRetries

​Use Exponential Backoff for Most Cases

​Consider API Rate Limits

​Monitor Retry Patterns

​Retry Event Lifecycle

​Configuration Limits

​Related Resources