Retrying

Retrying is appropriate for transient failures such as temporary network or service unavailability. It is not a substitute for handling permanent errors, and defects or interruptions are never retried.

retry

Effect.retry reruns an Effect after a typed failure. The source Effect is always evaluated once before the retry policy is applied.

Example (Retrying a Fixed Number of Times)

1
import { Data, Effect } from "effect"
2

3
class TemporaryError extends Data.TaggedError("TemporaryError")<{
4
  readonly attempt: number
5
}> {}
6

7
let attempts = 0
8
const request = Effect.suspend(() => {
9
  attempts++
10
  return attempts < 3
11
    ? Effect.fail(new TemporaryError({ attempt: attempts }))
12
    : Effect.succeed("ok")
13
})
14

15
const program = request.pipe(Effect.retry({ times: 5 }))
16

17
Effect.runSync(program) // => "ok"
18
attempts // => 3

times is the number of retries after the initial attempt. Therefore { times: 5 } allows at most six executions of the source Effect.

Retrying Selected Errors

The options object can combine:

while: retry while the predicate is true;
until: stop retrying when the predicate is true;
times: limit the number of retries;
schedule: control timing and additional stopping conditions.

Predicates may return either a boolean or an Effect.

Example (Retrying Only Transient Errors)

1
import { Data, Effect, Exit } from "effect"
2

3
class RequestError extends Data.TaggedError("RequestError")<{
4
  readonly retryable: boolean
5
}> {}
6

7
let attempts = 0
8
const request = Effect.failSync(() => {
9
  attempts++
10
  return new RequestError({ retryable: attempts < 2 })
11
})
12

13
const program = request.pipe(
14
  Effect.retry({
15
    times: 5,
16
    while: (error) => error.retryable,
17
  }),
18
)
19

20
Effect.runSyncExit(program) // => Exit.fail(new RequestError({ retryable: false }))
21
attempts // => 2

Using a Schedule

A Schedule can define delays, backoff, jitter, and retry limits. Schedule.recurs(3), for example, permits three retries after the initial attempt.

1
import { Effect, Schedule } from "effect"
2

3
let attempts = 0
4
const request = Effect.suspend(() => {
5
  attempts++
6
  return attempts < 2 ? Effect.fail("temporary") : Effect.succeed("ok")
7
})
8

9
const program = request.pipe(Effect.retry(Schedule.recurs(3)))
10

11
Effect.runSync(program) // => "ok"

Use Effect.repeat instead when repetition depends on successful values rather than errors.

retryOrElse

Effect.retryOrElse uses a Schedule and runs a fallback Effect when the schedule is exhausted. The fallback receives the final error and the schedule’s output.

Example (Falling Back After Retries)

1
import { Effect, Schedule } from "effect"
2

3
let attempts = 0
4
const request = Effect.failSync(() => {
5
  attempts++
6
  return "unavailable"
7
})
8

9
const program = Effect.retryOrElse(
10
  request,
11
  Schedule.recurs(2),
12
  (error, retries) => Effect.succeed(`${error} after ${retries} retries`),
13
)
14

15
Effect.runSync(program) // => "unavailable after 2 retries"
16
attempts // => 3