Reactで失敗したfetchを指数バックオフで再試行するフック
API のサーバーが一時的に 503 を返したり、通信が一瞬切れたりしたときに、待ち時間を 0.5秒、1秒、2秒と倍にしながら fetch をやり直す React のフックを作ります。この待ち方を指数バックオフと呼びます。データの読み込みにリトライ処理を付けたいが、TanStack Query などのライブラリは入れていない、という場面に使えます。
私は検証環境で、決まった順番でエラーを返す検証用のサーバーを作り、フックがいつ再試行したかを、画面の表示とサーバーが受けたリクエストの時刻で記録しました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。react / react-dom 19.3.1、@types/react / @types/react-dom 19.3.0、typescript 7.0.2、esbuild 0.28.2 を使いました。.tsx を tsc で型チェックしてから esbuild で本番用のビルドにし、Playwright 1.63.0 の Chromium で開いて動かしました。サーバーは、同じマシンで動かした Node.js の検証用のサーバーです。StrictMode を付けた開発用のビルド、Chromium 以外のブラウザ、Retry-After の日時の形式は試していません。
- 1. fetch は、404 や 503 では失敗しない
- 2. 待ち時間を倍にしていく関数と、中止できる待ち
- 3. 失敗したら待って、もう一度 fetch する
- 4. フックにして、コンポーネントから使う
- 5. 503 が続くと、0.5秒、1秒、2秒と間隔が広がる
- 6. 「もう一度読み込む」を押すと、最初から取得し直す
- 7. 404 は、すぐにあきらめる
- 8. 接続が切れたときは、TypeError で失敗する
- 9. Retry-After が付いた 429 では、指定された時間だけ待つ
- 10. 待っている間に画面を閉じると、次のリクエストは送られない
- 11. ジッターで、たくさんの再試行が同じ瞬間に重ならないようにする
- 12. TanStack Query を使っているなら、再試行は最初から入っている
fetch は、404 や 503 では失敗しない
最初に押さえておくことがあります。MDN の fetch() のページにあるとおり、fetch() の Promise が reject されるのは、ネットワークエラーなどでリクエストそのものが失敗したときだけです。サーバーが 404 や 504 などのエラーのステータスを返しても、reject されません。
そのため、再試行するかどうかは、次の2つを自分で見分けます。
res.okがfalseのとき(ステータスが 200〜299 以外)fetch()が例外を投げたとき(サーバーにつながらなかったとき)
ステータスのほうは、独自のエラークラス HttpError にして投げます。どのステータスでもやり直すわけではありません。404(見つからない)などは、再試行せず、すぐにあきらめます。この記事では、408、429、500、502、503、504 の6つを再試行の対象に選びました。
export class HttpError extends Error {
constructor(
public status: number,
public retryAfterMs: number | null,
) {
super(`HTTP ${status}`);
this.name = 'HttpError';
}
}
// やり直す価値のあるステータスコード(一時的な失敗)
const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
export function isRetryable(error: unknown): boolean {
if (error instanceof HttpError) return RETRYABLE_STATUS.has(error.status);
// fetch は、サーバーにつながらないときに TypeError で失敗する
return error instanceof TypeError;
}
待ち時間を倍にしていく関数と、中止できる待ち
待ち時間は base * 2 ** retry で求めます。base が 500 なら、500、1000、2000、4000ミリ秒と倍になります。どこまでも伸びないよう、max で頭打ちにします。jitter については、後の節で説明します。
// retry 回目(0 から数える)の待ち時間。base の 2 倍ずつ伸ばし、max で頭打ちにする
export function backoffDelay(retry: number, base: number, max: number, jitter: boolean): number {
const delay = Math.min(max, base * 2 ** retry);
// ジッター:0 から delay までの間で、ランダムに選ぶ
return jitter ? Math.round(Math.random() * delay) : delay;
}
待つ処理は setTimeout を Promise で包みます。ただし、待っている途中で画面を閉じたときに、そのまま次のリクエストを送ってしまわないよう、AbortSignal を受け取って、中止されたらタイマーを消してすぐに抜けるようにしました。
// 待っている途中で中止されたら、タイマーを消してすぐに抜ける
function sleep(ms: number, signal?: AbortSignal): Promise<void> {
return new Promise((resolve, reject) => {
if (signal?.aborted) return reject(signal.reason);
const timer = setTimeout(() => {
signal?.removeEventListener('abort', onAbort);
resolve();
}, ms);
function onAbort() {
clearTimeout(timer);
reject(signal!.reason);
}
signal?.addEventListener('abort', onAbort, { once: true });
});
}
失敗したら待って、もう一度 fetch する
部品を組み合わせて、再試行する fetchWithRetry を作ります。成功したら JSON を返します。中止されたとき、回数を使い切ったとき、再試行の対象でないときは、エラーをそのまま投げます。それ以外のときは、待ってからループの先頭に戻ります。
export type RetryInfo = { retry: number; delay: number; error: unknown };
export type FetchRetryOptions = {
retries: number;
baseDelay: number;
maxDelay: number;
jitter: boolean;
signal?: AbortSignal;
onRetry?: (info: RetryInfo) => void;
};
export async function fetchWithRetry<T>(url: string, options: FetchRetryOptions): Promise<T> {
const { retries, baseDelay, maxDelay, jitter, signal, onRetry } = options;
for (let retry = 0; ; retry++) {
try {
const res = await fetch(url, { signal });
if (!res.ok) {
throw new HttpError(res.status, parseRetryAfter(res.headers.get('Retry-After')));
}
return (await res.json()) as T;
} catch (error) {
if (signal?.aborted || retry >= retries || !isRetryable(error)) throw error;
let delay = backoffDelay(retry, baseDelay, maxDelay, jitter);
if (error instanceof HttpError && error.retryAfterMs !== null) {
// サーバーが指定した時間が上限より長いなら、待たずにあきらめる
if (error.retryAfterMs > maxDelay) throw error;
delay = Math.max(delay, error.retryAfterMs);
}
onRetry?.({ retry: retry + 1, delay, error });
await sleep(delay, signal);
}
}
}
retries は「最初の1回のあとに、何回やり直すか」です。3なら、リクエストは最大4回です。onRetry は、画面に「何秒後に再試行します」と出すために使います。
Retry-After は、サーバーが「これだけ待ってから送り直して」と伝えるレスポンスヘッダーです。MDN の Retry-After のページによると、503 ではサービスが使えない状態が続く見込みの時間を、429(リクエストが多すぎる)では次のリクエストまで待つ時間を表します。値は秒数か日時のどちらかです。秒数と日時の両方を、待つミリ秒に直す関数を用意しました。
// Retry-After の「秒数」と「日時」の両方を、待つミリ秒に直す
export function parseRetryAfter(value: string | null): number | null {
if (value === null) return null;
if (/^\d+$/.test(value)) return Number(value) * 1000;
const date = Date.parse(value);
return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
}
フックにして、コンポーネントから使う
useEffect の中で fetchWithRetry を呼び、片付け関数で abort() します。useEffect のリファレンスにあるとおり、片付け関数は依存する値が変わったときと、コンポーネントが画面から消えたときに呼ばれます。再試行までの待ち時間の途中で画面から消したときの動きは、後の節で確かめています。
import { useCallback, useEffect, useState } from 'react';
import { fetchWithRetry } from './fetchWithRetry';
export type RetryOptions = {
retries?: number;
baseDelay?: number;
maxDelay?: number;
jitter?: boolean;
};
type Result<T> =
| { status: 'loading' }
| { status: 'retrying'; retry: number; delay: number; error: unknown }
| { status: 'success'; data: T }
| { status: 'error'; error: unknown };
export function useFetchWithRetry<T>(url: string, options: RetryOptions = {}) {
const { retries = 3, baseDelay = 500, maxDelay = 8000, jitter = true } = options;
const [reloadCount, setReloadCount] = useState(0);
// どのリクエストの結果かを key で覚えておく
const key = `${url}#${reloadCount}`;
const [state, setState] = useState<{ key: string; result: Result<T> } | null>(null);
useEffect(() => {
const controller = new AbortController();
fetchWithRetry<T>(url, {
retries,
baseDelay,
maxDelay,
jitter,
signal: controller.signal,
onRetry: ({ retry, delay, error }) =>
setState({ key, result: { status: 'retrying', retry, delay, error } }),
}).then(
(data) => setState({ key, result: { status: 'success', data } }),
(error) => {
// 片付けで中止したときは、何も表示を変えない
if (controller.signal.aborted) return;
setState({ key, result: { status: 'error', error } });
},
);
return () => controller.abort();
}, [key, url, retries, baseDelay, maxDelay, jitter]);
const reload = useCallback(() => setReloadCount((c) => c + 1), []);
// key が変わった直後は、まだ前の結果が残っているので「読み込み中」として返す
const result: Result<T> = state?.key === key ? state.result : { status: 'loading' };
return { ...result, reload };
}
結果には key(URL と再読み込みの回数)を一緒に入れておき、いまの key と違う結果は「読み込み中」として扱います。URL が変わったときや「もう一度読み込む」を押したときに、エフェクトの中で同期的に setState を呼ばずに、前の結果を表示から外すためです。
使う側のコンポーネントです。status ごとに表示を分けます。
import { useFetchWithRetry } from './useFetchWithRetry';
type Cat = { name: string };
export function CatProfile({ url, jitter = false }: { url: string; jitter?: boolean }) {
const cat = useFetchWithRetry<Cat>(url, { retries: 3, baseDelay: 500, jitter });
switch (cat.status) {
case 'loading':
return <p>読み込み中…</p>;
case 'retrying':
return (
<p>
失敗しました({String(cat.error)})。{cat.delay} ミリ秒後に再試行します({cat.retry}/3 回目)
</p>
);
case 'error':
return (
<p>
読み込めませんでした({String(cat.error)})
<button onClick={cat.reload}>もう一度読み込む</button>
</p>
);
case 'success':
return <p>名前:{cat.data.name}</p>;
}
}
この記事のフックは、データを読むだけの GET リクエストに使う前提で作っています。フックの jitter の初期値は true ですが、待ち時間の変化が分かりやすいよう、CatProfile では false にして検証しています(ジッターの節を除く)。
503 が続くと、0.5秒、1秒、2秒と間隔が広がる
サーバーが 503 を2回返したあと、3回目で 200 を返すようにしました。画面の時刻はページを開いてから、サーバーの時刻は1回目のリクエストを受けてからのミリ秒です。
$ node run.mjs flaky
画面 + 1ms: (表示なし)
画面 + 37ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 51ms: 失敗しました(HttpError: HTTP 503)。500 ミリ秒後に再試行します(1/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 553ms: 失敗しました(HttpError: HTTP 503)。1000 ミリ秒後に再試行します(2/3 回目)
画面 + 1556ms: 名前:たま
サーバーが受けたリクエスト:
+ 0ms 1回目 → 503
+ 503ms 2回目 → 503
+ 1506ms 3回目 → 200
2回目のリクエストは約0.5秒後、3回目はそこから約1秒後にサーバーに届き、3回目の成功で名前が表示されました。[console.error] の行は、Chromium がエラーのステータスを受け取ったときに、コンソールに自動で出したものです。
同じ動きを画面で見ると、次のようになります。

サーバーがずっと 503 を返す場合は、3回やり直したところであきらめます。
$ node run.mjs down --wait=6000
画面 + 1ms: (表示なし)
画面 + 35ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 40ms: 失敗しました(HttpError: HTTP 503)。500 ミリ秒後に再試行します(1/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 543ms: 失敗しました(HttpError: HTTP 503)。1000 ミリ秒後に再試行します(2/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 1546ms: 失敗しました(HttpError: HTTP 503)。2000 ミリ秒後に再試行します(3/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 3550ms: 読み込めませんでした(HttpError: HTTP 503)もう一度読み込む
サーバーが受けたリクエスト:
+ 0ms 1回目 → 503
+ 504ms 2回目 → 503
+ 1507ms 3回目 → 503
+ 3510ms 4回目 → 503
リクエストは合計4回で、間隔は約0.5秒、1秒、2秒でした。4回目も失敗したところで、「読み込めませんでした」と「もう一度読み込む」のボタンが出ました。
「もう一度読み込む」を押すと、最初から取得し直す
4回目まで 503 を返し、5回目で 200 を返すようにしました。エラーが表示されたあとで「もう一度読み込む」を押しています。
$ node run.mjs reload --click-reload-after=4000 --wait=2000
画面 + 1ms: (表示なし)
画面 + 34ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 38ms: 失敗しました(HttpError: HTTP 503)。500 ミリ秒後に再試行します(1/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 542ms: 失敗しました(HttpError: HTTP 503)。1000 ミリ秒後に再試行します(2/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 1546ms: 失敗しました(HttpError: HTTP 503)。2000 ミリ秒後に再試行します(3/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 3548ms: 読み込めませんでした(HttpError: HTTP 503)もう一度読み込む
--- ここで「もう一度読み込む」を押す ---
画面 + 4084ms: 読み込み中…
画面 + 4093ms: 名前:たま
サーバーが受けたリクエスト:
+ 0ms 1回目 → 503
+ 503ms 2回目 → 503
+ 1507ms 3回目 → 503
+ 3510ms 4回目 → 503
+ 4050ms 5回目 → 200
ボタンを押すと reloadCount が増えて key が変わり、前のエラーの代わりに「読み込み中…」が出ました。続いて新しいリクエスト(サーバーでは5回目)が送られ、名前が表示されました。
404 は、すぐにあきらめる
404 は再試行の対象に入れていないので、1回で終わります。
$ node run.mjs notfound
画面 + 1ms: (表示なし)
画面 + 30ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 404 (Not Found)
画面 + 37ms: 読み込めませんでした(HttpError: HTTP 404)もう一度読み込む
サーバーが受けたリクエスト:
+ 0ms 1回目 → 404
接続が切れたときは、TypeError で失敗する
サーバーが応答を返さずに接続を切る場合も試しました。最初の2回のリクエストで接続を切り、3回目で 200 を返します。
$ node run.mjs network2
画面 + 1ms: (表示なし)
画面 + 33ms: 読み込み中…
[console.error] Failed to load resource: net::ERR_EMPTY_RESPONSE
画面 + 46ms: 失敗しました(TypeError: Failed to fetch)。500 ミリ秒後に再試行します(1/3 回目)
画面 + 550ms: 名前:たま
サーバーが受けたリクエスト:
+ 0ms 1回目 → 接続を切断
+ 1ms 2回目 → 接続を切断
+ 505ms 3回目 → 200
fetch() は TypeError: Failed to fetch で失敗し、フックは 0.5秒待ってから送り直しました。
サーバーの記録を見ると、1回目と2回目は1ミリ秒しか離れていません。フックの再試行は1回だけなので、2回目は検証環境の Chromium が自分で送り直したものです。接続を切るのを1回目だけにしたときは、ブラウザが送り直した2回目が 200 を受け取り、フックには失敗がまったく届きませんでした。
$ node run.mjs network
画面 + 1ms: (表示なし)
画面 + 36ms: 読み込み中…
画面 + 51ms: 名前:たま
サーバーが受けたリクエスト:
+ 0ms 1回目 → 接続を切断
+ 2ms 2回目 → 200
Retry-After が付いた 429 では、指定された時間だけ待つ
429 に Retry-After: 2 を付けて返し、2回目で 200 を返すようにしました。指数バックオフでは 500ミリ秒のところですが、Math.max でサーバーが指定した2秒が選ばれます。
$ node run.mjs ratelimit
画面 + 1ms: (表示なし)
画面 + 36ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 429 (Too Many Requests)
画面 + 42ms: 失敗しました(HttpError: HTTP 429)。2000 ミリ秒後に再試行します(1/3 回目)
画面 + 2045ms: 名前:たま
サーバーが受けたリクエスト:
+ 0ms 1回目 → 429 Retry-After: 2
+ 2004ms 2回目 → 200
Retry-After: 30 のように、上限の maxDelay(8000ミリ秒)より長い時間を指定されたときは、待たずにあきらめるようにしてあります。30秒も待たせずにすぐにエラーを出して、使う人が「もう一度読み込む」を押せるようにするためです。
$ node run.mjs longwait
画面 + 0ms: (表示なし)
画面 + 41ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 429 (Too Many Requests)
画面 + 54ms: 読み込めませんでした(HttpError: HTTP 429)もう一度読み込む
サーバーが受けたリクエスト:
+ 0ms 1回目 → 429 Retry-After: 30
待っている間に画面を閉じると、次のリクエストは送られない
サーバーがずっと 503 を返す状態で、ページの読み込みが終わってから0.7秒後に、CatProfile を画面から消すボタン「閉じる」を押しました(画面の記録では約0.8秒の時点です)。そのあと5秒待っています。
$ node run.mjs down --close-after=700 --wait=5000
画面 + 1ms: (表示なし)
画面 + 29ms: 読み込み中…
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 34ms: 失敗しました(HttpError: HTTP 503)。500 ミリ秒後に再試行します(1/3 回目)
[console.error] Failed to load resource: the server responded with a status of 503 (Service Unavailable)
画面 + 537ms: 失敗しました(HttpError: HTTP 503)。1000 ミリ秒後に再試行します(2/3 回目)
画面 + 776ms: (表示なし)
サーバーが受けたリクエスト:
+ 0ms 1回目 → 503
+ 504ms 2回目 → 503
閉じずに待った場合は、503 が続くときの検証のとおり、約1.5秒のところで3回目が届きます。今回は、サーバーが受けたリクエストが2回で止まりました。コードでは、片付け関数の abort() で sleep のタイマーが消え、ループから抜ける作りです。
ジッターで、たくさんの再試行が同じ瞬間に重ならないようにする
同じ API を使うコンポーネントがたくさんあると、サーバーが止まった瞬間に、すべてのコンポーネントが同時に失敗し、同じ時間だけ待って、同時に送り直すことになります。これを確かめるため、CatProfile を20個並べ、どれも1回目は 503、2回目は 200 を返すようにしました。
$ node run.mjs herd --count=20 --json=herd-off.json
1回目のリクエスト: 20件, 0〜12ms
2回目のリクエストの時刻(ms): 505, 518, 520, 521, 522, 523, 524, 526, 526, 526, 526, 527, 527, 528, 528, 528, 528, 528, 529, 530
2回目が届いた範囲: 505〜530ms(幅 25ms)
最後の画面: 「名前:たま」が 20/20 件
ジッターなしでは、20件の再試行が25ミリ秒の間にまとまって届きました。
backoffDelay の jitter を true にすると、待ち時間を 0 から上限(ここでは 500ミリ秒)までの間でランダムに選びます。
$ node run.mjs herd --count=20 --jitter --json=herd-on.json
1回目のリクエスト: 20件, 0〜12ms
2回目のリクエストの時刻(ms): 19, 43, 61, 72, 77, 92, 138, 164, 180, 188, 196, 250, 277, 296, 308, 344, 346, 408, 442, 469
2回目が届いた範囲: 19〜469ms(幅 450ms)
最後の画面: 「名前:たま」が 20/20 件

ジッターありでは、同じ20件が約0.5秒の間に散らばりました。復旧したばかりのサーバーに、一度にリクエストが押し寄せるのを和らげられます。そのぶん、待ち時間が 0 に近くなるコンポーネントも出ます。
TanStack Query を使っているなら、再試行は最初から入っている
TanStack Query の useQuery は、何も設定しなくても失敗したクエリを再試行します。TanStack Query の再試行のガイドによると、ブラウザでの再試行は既定で3回、待ち時間の既定は Math.min(1000 * 2 ** attemptIndex, 30000) で、1秒から倍にしていき30秒で頭打ちになります。retry に関数を渡せば、エラーの内容でやり直すかどうかを決められます。すでに TanStack Query を使っているなら、この記事のフックを足すより、その設定を調整するほうが簡単です。





