Retries with backoff | Fern Documentation

Fern SDKs will automatically retry failed requests with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit.

Retryable status codes

A request is deemed retryable when any of the following HTTP status codes is returned:

408 (Timeout)
429 (Too Many Requests)
5XX (Internal Server Errors)

In the Java SDK, retryOnStatusCodes on the client builder replaces this default set. The configured codes are the only ones retried, and any other response (including other 5XX codes) is returned as-is. Each code must be between 100 and 599. The retry limit, backoff settings, and Retry-After handling are unchanged, and the setting applies to both sync and async clients.

Java

import com.imdb.ImdbClient;
import java.util.Set;
// retries only 429 and 503; other 5XX responses are returned without retrying
ImdbClient client = new ImdbClient.Builder()
  .retryOnStatusCodes(Set.of(429, 503))
  .build();

Overriding the retry limit

By default, the SDK will retry a failed request up to 2 times. SDK users can override the global default retry limit when instantiating the client.

import { ImdbClient } from "imdb";
const client = new ImdbClient({
  maxRetries: 1 // overrides the default retry limit to 1
});

It’s also possible to override the retry limit on a per-request basis.

  client.movie.get("tt0111161", {
    maxRetries: 3 // overrides the default retry limit to 3
  });

Customizing the backoff schedule

The Java SDK exposes client builder options to tune the exponential backoff applied between retries, alongside maxRetries.

Java

import com.imdb.ImdbClient;
ImdbClient client = new ImdbClient.Builder()
  .maxRetries(3)
  .initialRetryDelayMillis(500)
  .maxRetryDelayMillis(30000)
  .retryJitterFactor(0.1)
  .build();

Option	Description	Default
`initialRetryDelayMillis`	Initial delay in milliseconds used for exponential backoff.	`1000`
`maxRetryDelayMillis`	Maximum delay in milliseconds between retries.	`60000`
`retryJitterFactor`	Jitter factor between 0 and 1 applied to retry delays.	`0.2`
`retryDelays`	Explicit list of delays (`List<Duration>`) to wait before each retry. Replaces `maxRetries` and the exponential backoff options.	Not set

To use a fixed retry schedule instead of exponential backoff, pass retryDelays. The n-th retry waits for the n-th duration, and retrying stops once the list is exhausted, so the list size replaces maxRetries (a per-request maxRetries override can still lower it). Delays are used as-is without jitter, and initialRetryDelayMillis, maxRetryDelayMillis, and retryJitterFactor are ignored. A Retry-After or X-RateLimit-Reset response header still takes precedence for that attempt. An empty list disables retries.

Java

import com.imdb.ImdbClient;
import java.time.Duration;
import java.util.List;
import java.util.Set;
ImdbClient client = new ImdbClient.Builder()
  .retryOnStatusCodes(Set.of(429))
  .retryDelays(List.of(
    Duration.ofSeconds(1),
    Duration.ofSeconds(5),
    Duration.ofSeconds(30),
    Duration.ofSeconds(60)
  ))
  .build();