外の API を呼ぶとき、タイムアウトと再試行をどう決めますか

タイムアウトを置かないと何が起きるか

ライブラリによっては、既定の待ち時間がとても長かったり、無かったりします。相手が応答を返さなくなると、自分のサーバーはリクエストを抱えたまま待ち続け、接続やスレッドが埋まって、外の API と関係の無い画面まで遅くなります。外を呼ぶ所には、必ず自分でタイムアウトを置きます。ブラウザや Node.js の fetch なら、AbortSignal.timeout() で打ち切れます。

何秒にするか

根拠は 2 つです。

• 相手の速さ 監視で、相手の応答時間の遅いほう (上から 1% の人が待つ時間など) を見て、それに少し余裕を足します。平均を基準にすると、ふつうの遅い応答まで切ってしまいます
• 自分の持ち時間利用者に 2 秒で返すと決めているなら、外の呼び出しと再試行の合計を、その中に収めます。上の層の持ち時間より、下の層のタイムアウトを長くしても意味がありません

つなぐまでの時間と、つないでから応答を待つ時間を分けて置ける道具なら、つなぐまでは短めにします。つながらない相手を長く待つ理由は無いからです。

再試行してよい失敗

再試行してよいのは、次の両方を満たすときです。

• 一時的な失敗である通信の切れ、タイムアウト、混み合いを表す 429、502、503、504 など。400 や 404 のような入力や権限の誤りは、何度送っても同じなので再試行しません
• 何度送っても困らない呼び出しである読むだけの呼び出しや、冪等キーを付けた呼び出しです。決済のような呼び出しを鍵なしで再試行すると、二重に処理されることがあります

相手が Retry-After のヘッダーで「これだけ待ってから」と返してきたら、それに従います。

間隔を倍々に広げる

すぐにやり直すと、混んでいる相手をさらに混ませます。間隔を倍々に広げ (指数バックオフ)、上限で止めます。下の例では、待ち時間を 200 ミリ秒から倍にし、2 秒で頭打ちにしています。

function backoffDelays(base, cap, retries) {
  const delays = [];
  for (let i = 0; i < retries; i++) {
    delays.push(Math.min(cap, base * 2 ** i));
  }
  return delays;
}

function shouldRetry(status, idempotent) {
  if (!idempotent) {
    return false;
  }
  return [429, 502, 503, 504].includes(status);
}

console.log(backoffDelays(200, 2000, 5).join(" "));
console.log(shouldRetry(503, true));
console.log(shouldRetry(400, true));
console.log(shouldRetry(503, false));

200 400 800 1600 2000
true
false
false

実際には、この待ち時間にばらつき (ジッター) を足します。多くの呼び出し元が同じ時刻に失敗すると、同じ間隔で一斉にやり直し、また一斉に相手を叩くからです。

再試行は 1 つの層でだけ

画面、自分の API、その先の API、と 3 つの層がそれぞれ 3 回ずつ試すと、いちばん下には最大で 3 × 3 × 3 = 27 回の呼び出しが届きます。相手が弱っているときほど呼び出しが増え、立ち直れなくなります。どの層で再試行するかを 1 つに決め、ほかの層は失敗をそのまま上へ返します。

トレードオフ

タイムアウトを短くすると、自分は早く諦められますが、相手が少し遅いだけの成功も失敗にしてしまいます。再試行を増やすと成功の割合は上がりますが、利用者を待たせ、相手の負担も増えます。外の API が止まっても自分のサービスを動かしたいなら、再試行で粘るより、早く諦めて代わりの表示に切り替えるほうがよいこともあります。

話す例は架空の例で構いません。「外の住所の検索の API が時々遅く、タイムアウトが無くて画面ごと固まったので、応答時間の記録から 1.5 秒に決め、再試行は 1 回だけにした」のように、数字の根拠を添えて話せると伝わります。