Retry

The retry option enables automatic retry logic for transient errors. When a request fails due to a server-side 5xx error or a network fault, the client waits and tries again — up to a configurable number of times, with exponentially increasing delays between attempts.

It is opt-in — disabled by default with no behaviour change for existing consumers.

Enabling retry

Pass retry: true to use the built-in defaults:

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB("your-api-key", { retry: true });

Defaults:

Custom options

Pass a RetryOptions object to override individual settings:

const tmdb = new TMDB("your-api-key", {
	retry: {
		max_retries: 5,
		base_delay_ms: 200,
		max_delay_ms: 10_000,
	},
});

Which errors are retried

By default, the following errors trigger a retry:

• HTTP 5xx responses — TMDBError instances with http_status_code >= 500 (e.g. 500 Internal Server Error, 503 Service Unavailable)
• Network / DNS errors — any non-TMDBError exception thrown by the underlying fetch (e.g. connection reset, timeout, offline)

4xx client errors are never retried by default because they indicate a caller-side problem (wrong parameters, invalid token, resource not found) that won't resolve on its own.

Custom shouldRetry predicate

Override the retry decision entirely by providing a synchronous or async shouldRetry function:

import { TMDBError } from "@lorenzopant/tmdb";

const tmdb = new TMDB("your-api-key", {
	retry: {
		max_retries: 4,
		shouldRetry: (error, attempt) => {
			// Also retry 429 responses, but only on the first two attempts
			if (error instanceof TMDBError) {
				return error.http_status_code >= 500 || (error.http_status_code === 429 && attempt <= 2);
			}
			return true; // retry all network errors
		},
	},
});

The predicate receives:

Return true to retry, false to stop and re-throw immediately.

Back-off algorithm

The client uses full jitter exponential back-off:

delay = random(0, min(base_delay_ms * 2^(attempt-1), max_delay_ms))

Full jitter distributes retry load evenly across time, which prevents multiple clients from all retrying in tight synchrony after a server hiccup (the "thundering herd" problem).

Example delays with base_delay_ms: 500, max_delay_ms: 30_000:

Combining with rate limiting

Retry and rate limiting work together naturally. Each retry attempt acquires its own rate-limit slot before the fetch is dispatched, so retried requests respect the same budget as regular requests.

const tmdb = new TMDB("your-api-key", {
	rate_limit: true,
	retry: true,
});

Applies to mutations too

The retry option covers all HTTP methods — GET reads and POST / PUT / DELETE mutations — because transient server errors can affect any kind of request. If you only want to retry reads, supply a shouldRetry predicate that checks the request context through the error or limit retry to specific error codes.