# UTIL_Retry

**Class** · Group: `Resilience`

Learn it: [Fast Start - Resilience](/fast-start-resilience) and [Resilience guide](/resilience-guide)

<div class="apex-member apex-class">

```apex
global inherited sharing class UTIL_Retry
```

Factory for retry strategies with nested interface definitions. Provides a clean API for creating and configuring retry strategies with exponential or linear backoff. This factory pattern reduces namespace pollution by nesting the interface inside the factory class. Features: Nested interfaces for clean type organization Fluent configuration API Standard implementations (exponential, linear) Custom strategy support via interface Jitter support to prevent thundering herd

**Example**

Example 1: Simple exponential backoff

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.exponential();
UTIL_Retry.Context context = UTIL_Retry.newContext(1);
if(strategy.shouldRetry(context))
{
    Integer backoffSeconds = strategy.calculateBackoff(context);
    Datetime nextRetry = Datetime.now().addSeconds(backoffSeconds);
}
```

Example 2: Custom configuration

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.exponential()
    .withMaxRetries(5)
    .withBaseBackoff(10)
    .withJitter(true);
```

Example 3: Custom strategy implementation

```apex
public class RateLimitStrategy implements UTIL_Retry.Strategy
{
    public Boolean shouldRetry(UTIL_Retry.Context context)
    {
        return context.getRetryCount() < 3;
    }
    public Integer calculateBackoff(UTIL_Retry.Context context)
    {
        // Custom logic based on rate limit headers
        return 60; // Wait 1 minute for rate limit
    }
    // Implement fluent setters...
}
```

</div>

---

## Methods

| Method | Description |
|--------|-------------|
| global static [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) [dontRetryOnException](#dontretryonexception)([UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) base, [Set](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_set.htm)<[Type](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_type.htm)> exceptionTypes) | Wraps an existing strategy with an exception-type denylist. |
| global static [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) [exponential](#exponential)() | Returns a standard exponential backoff strategy. |
| global static [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) [linear](#linear)() | Returns a standard linear backoff strategy. |
| global static [UTIL_Retry.Context](/reference/apex/util-retry-context) [newContext](#newcontext)([Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) retryCount) | Starts the context a strategy reads to decide whether to retry and how long to wait. |
| global static [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) [retryOnlyOnException](#retryonlyonexception)([UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) base, [Set](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_set.htm)<[Type](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_type.htm)> exceptionTypes) | Wraps an existing strategy with an exception-type allowlist. |

### dontRetryOnException

<div class="apex-member">

```apex
global static UTIL_Retry.Strategy dontRetryOnException(UTIL_Retry.Strategy base, Set<Type> exceptionTypes)
```

Wraps an existing strategy with an exception-type denylist. The wrapped
strategy delegates `calculateBackoff` and the fluent setters (`withMaxRetries`, etc.)
to the base strategy, but `shouldRetry` returns `false` whenever the caught exception
(passed via `Context.withCustomData(Exception)`) matches any type in the denylist by
**exact type name** (e.g. `System.IllegalArgumentException`). Subclass relationships
are NOT considered — denylisting `Exception.class` does not catch concrete subclasses;
list each concrete type explicitly. Use for "never retry on these errors" cases — e.g.
authentication failures that won't recover via retry.

Wrapping (rather than adding setters to the `Strategy` interface) keeps the contract
for your own Strategy implementations unchanged.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `base` | [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) | The base retry strategy to wrap. |
| `exceptionTypes` | [Set](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_set.htm) | Set of exception types that should NEVER be retried. |

**Returns** [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) — A wrapped Strategy that suppresses retries when the caught exception matches any type in the denylist.

**Example**

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.dontRetryOnException(
        UTIL_Retry.exponential().withMaxRetries(5),
        new Set<Type>{System.IllegalArgumentException.class}
);
UTIL_Retry.Context context = UTIL_Retry.newContext(0).withCustomData(caughtException);
Boolean shouldRetry = strategy.shouldRetry(context);
```

</div>

### exponential

<div class="apex-member">

```apex
global static UTIL_Retry.Strategy exponential()
```

Returns a standard exponential backoff strategy.
Defaults: max retries = 3, base backoff = 10s, jitter = false

**Returns** [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) — Configured exponential backoff strategy

**Example**

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.exponential()
    .withMaxRetries(5)
    .withJitter(true);
```

</div>

### linear

<div class="apex-member">

```apex
global static UTIL_Retry.Strategy linear()
```

Returns a standard linear backoff strategy.
Defaults: max retries = 3, base backoff = 10s

**Returns** [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) — Configured linear backoff strategy

**Example**

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.linear()
    .withMaxRetries(5)
    .withBaseBackoff(15);
```

</div>

### newContext

<div class="apex-member">

```apex
global static UTIL_Retry.Context newContext(Integer retryCount)
```

Starts the context a strategy reads to decide whether to retry and how long to wait. A null or
negative count is treated as 0. Add the time of the last attempt and any data of your own, such as the caught
exception, with withLastAttemptTime and withCustomData.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `retryCount` | [Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) | The current retry attempt number (0 = first attempt, 1 = first retry, etc.) |

**Returns** [UTIL_Retry.Context](/reference/apex/util-retry-context) — New context instance

**Example**

```apex
UTIL_Retry.Context context = UTIL_Retry.newContext(1)
    .withLastAttemptTime(Datetime.now())
    .withCustomData(apiCall);
```

</div>

### retryOnlyOnException

<div class="apex-member">

```apex
global static UTIL_Retry.Strategy retryOnlyOnException(UTIL_Retry.Strategy base, Set<Type> exceptionTypes)
```

Wraps an existing strategy with an exception-type allowlist. The wrapped
strategy delegates everything to the base, but `shouldRetry` returns `false` UNLESS
the caught exception (passed via `Context.withCustomData(Exception)`) matches one of
the allowed types by **exact type name**. Subclass relationships are NOT considered.
Use for "only retry on these errors" cases — e.g. a narrow set of transient errors a
remote service might throw.

Calls without a caught Exception in `Context.getCustomData()` always retry per the
base strategy (the allowlist only applies when an exception is present).

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `base` | [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) | The base retry strategy to wrap. |
| `exceptionTypes` | [Set](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_set.htm) | Set of exception types that ARE allowed to be retried. Empty or null disables the filter (delegates fully to base). |

**Returns** [UTIL_Retry.Strategy](/reference/apex/util-retry-strategy) — A wrapped Strategy that only retries when the caught exception matches an allowed type.

**Example**

```apex
UTIL_Retry.Strategy strategy = UTIL_Retry.retryOnlyOnException(
        UTIL_Retry.exponential().withMaxRetries(5),
        new Set<Type>{System.CalloutException.class}
);
```

</div>

## Inner Classes

| Class | Description |
|-------|-------------|
| [Context](/reference/apex/util-retry-context) | Interface defining the retry context. |
| [Strategy](/reference/apex/util-retry-strategy) | Interface defining the retry strategy logic. |

---
