> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cuey.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retry Configuration

> Configure retry logic for failed webhook deliveries

## 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:

```json theme={null}
{
  "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):

1. A new retry event is created
2. The retry event inherits the original event's configuration
3. The retry event is scheduled with the configured backoff delay
4. 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "maxRetries": 3,
  "backoffMs": 500,
  "backoffType": "exponential"
}
```

## Configuration Examples

### Quick Retries (Transient Errors)

For transient errors that resolve quickly:

```json theme={null}
{
  "maxRetries": 5,
  "backoffMs": 500,
  "backoffType": "exponential"
}
```

### Aggressive Retries (Critical Operations)

For critical operations that must succeed:

```json theme={null}
{
  "maxRetries": 10,
  "backoffMs": 1000,
  "backoffType": "exponential"
}
```

### Slow Retries (Rate-Limited APIs)

For APIs that may be rate-limited:

```json theme={null}
{
  "maxRetries": 3,
  "backoffMs": 5000,
  "backoffType": "linear"
}
```

### No Retries

To disable retries, set `maxRetries` to 1:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

1. **Original Event Fails**: Event status changes to `failed`
2. **Retry Event Created**: New event created with `retry_of` pointing to original
3. **Retry Scheduled**: Retry event scheduled with backoff delay
4. **Retry Executed**: Retry event attempts webhook delivery
5. **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     |

## Related Resources

<CardGroup cols={2}>
  <Card title="Retrying Events" icon="exclamation-triangle" href="/concepts/retrying-events">
    Learn how retries work.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/typescript-client/overview">
    Get started with the TypeScript SDK.
  </Card>

  <Card title="REST API" icon="plug" href="/api-reference/introduction">
    Explore the REST API documentation.
  </Card>
</CardGroup>