Reactで失敗したfetchを指数バックオフで再試行するフック

​​React​fetch,TypeScript,カスタムフック

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 の日時の形式は試していません。

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つを再試行の対象に選びました。

ts
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 については、後の節で説明します。

ts
// 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 を受け取って、中止されたらタイマーを消してすぐに抜けるようにしました。

ts
// 待っている途中で中止されたら、タイマーを消してすぐに抜ける
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 を返します。中止されたとき、回数を使い切ったとき、再試行の対象でないときは、エラーをそのまま投げます。それ以外のときは、待ってからループの先頭に戻ります。

ts
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(リクエストが多すぎる)では次のリクエストまで待つ時間を表します。値は秒数か日時のどちらかです。秒数と日時の両方を、待つミリ秒に直す関数を用意しました。

ts
// 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 のリファレンスにあるとおり、片付け関数は依存する値が変わったときと、コンポーネントが画面から消えたときに呼ばれます。再試行までの待ち時間の途中で画面から消したときの動きは、後の節で確かめています。

tsx
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 ごとに表示を分けます。

tsx
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回目のリクエストを受けてからのミリ秒です。

text
$ 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 がエラーのステータスを受け取ったときに、コンソールに自動で出したものです。

同じ動きを画面で見ると、次のようになります。

「読み込む」を押すと、画面に、HTTP 503 で失敗して500ミリ秒後に再試行するという表示、続いて1000ミリ秒後に再試行するという表示が順に出て、最後に「名前:たま」になる。下の一覧には、サーバーが受けたリクエストが 0.00秒 503、0.51秒 503、1.51秒 200 と増えていく
「読み込む」を1回押したあと、503 が2回続き、3回目で成功するまでの表示の移り変わり

サーバーがずっと 503 を返す場合は、3回やり直したところであきらめます。

text
$ 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 を返すようにしました。エラーが表示されたあとで「もう一度読み込む」を押しています。

text
$ 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回で終わります。

text
$ 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 を返します。

text
$ 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 を受け取り、フックには失敗がまったく届きませんでした。

text
$ 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秒が選ばれます。

text
$ 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秒も待たせずにすぐにエラーを出して、使う人が「もう一度読み込む」を押せるようにするためです。

text
$ 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秒待っています。

text
$ 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 を返すようにしました。

text
$ 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ミリ秒)までの間でランダムに選びます。

text
$ 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 件
2回目のリクエストが届いた時刻を25ミリ秒ごとの件数で表した棒グラフ。ジッターなしでは500〜550ミリ秒の2本に20件が集まり、ジッターありでは19〜469ミリ秒の間に1〜3件ずつ散らばっている
20個のコンポーネントが同時に失敗したあと、2回目のリクエストが届いた時刻。上がジッターなし、下がジッターあり

ジッターありでは、同じ20件が約0.5秒の間に散らばりました。復旧したばかりのサーバーに、一度にリクエストが押し寄せるのを和らげられます。そのぶん、待ち時間が 0 に近くなるコンポーネントも出ます。

TanStack Query を使っているなら、再試行は最初から入っている

TanStack Query の useQuery は、何も設定しなくても失敗したクエリを再試行します。TanStack Query の再試行のガイドによると、ブラウザでの再試行は既定で3回、待ち時間の既定は Math.min(1000 * 2 ** attemptIndex, 30000) で、1秒から倍にしていき30秒で頭打ちになります。retry に関数を渡せば、エラーの内容でやり直すかどうかを決められます。すでに TanStack Query を使っているなら、この記事のフックを足すより、その設定を調整するほうが簡単です。

​Posted by 86