Retry Transient Errors

HttpClient.retryTransient() is a purpose-built retry combinator for the most common case: retrying requests that fail due to temporary issues like network errors, timeouts, or rate limiting.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
} from "effect/unstable/http";
6
import { Effect, Schedule } from "effect";
7

8
function fetchWithTransientRetry(userId: number) {
9
  return Effect.gen(function* () {
10
    const client = (yield* HttpClient.HttpClient).pipe(
11
      HttpClient.filterStatusOk,
12
      HttpClient.retryTransient({
13
        times: 3,
14
        schedule: Schedule.exponential("500 millis"),
15
      }),
16
    );
17

18
    const request = HttpClientRequest.get(
19
      `https://dummyjson.com/users/${userId}`,
20
    );
21

22
    const response = yield* client.execute(request);
23
    const user = yield* response.json;
24

25
    return user;
26
  }).pipe(Effect.provide(FetchHttpClient.layer));
27
}
28

29
// Test it
30
Effect.runPromise(fetchWithTransientRetry(1)).then(
31
  (user) => console.log("User:", user.firstName, user.lastName),
32
  (error) => console.error("Failed after retries:", error.message),
33
);

Output:

1
User: Emily Johnson

Unlike retry, which retries on all errors, retryTransient only retries errors that are classified as transient. Specifically, it retries when:

• The error is a TimeoutException (from Effect.timeout)
• The error is an HttpClientError with a TransportError reason (network failures like DNS resolution, connection refused, etc.)
• The error is an HttpClientError with a StatusCodeError reason where the status code is 408 (Request Timeout), 429 (Too Many Requests), 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), or 504 (Gateway Timeout)

A 404 or 400 won’t be retried because those aren’t transient. Retrying them would give the same result.

You can also pass just a Schedule directly:

1
HttpClient.retryTransient(
2
  Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5))),
3
);

The mode option lets you control what the schedule receives as input. By default, it receives both errors and responses. You can narrow this:

1
// Only consider errors for scheduling (ignore response status)
2
HttpClient.retryTransient({
3
  mode: "errors-only",
4
  times: 3,
5
  schedule: Schedule.exponential("500 millis"),
6
});
7

8
// Only consider response status for scheduling (ignore errors)
9
HttpClient.retryTransient({
10
  mode: "response-only",
11
  times: 3,
12
  schedule: Schedule.exponential("500 millis"),
13
});

If you have additional error types that should be considered transient, use the while predicate:

1
HttpClient.retryTransient({
2
  times: 3,
3
  while: (error) => error._tag === "TransportError",
4
});

The while predicate is checked in addition to the built-in transient checks. It lets you widen the set of retryable errors without replacing the defaults.

For most applications, retryTransient with a schedule and a times cap is the right default. It handles the common failure modes — network blips, rate limits, server hiccups, and timeouts — without retrying errors that can’t be fixed by waiting.