APIのタイムアウトとリトライの決め方|待ち時間・回数・間隔と、やってはいけない再試行

決めていないと、何が起きるか

APIを呼ぶコードを書く時、「いつまで待つか」「失敗したら、何回やり直すか」を、決めていないことがあります。すると、次のような問題が起きます。

これらは、運用で障害が起きた時に、初めて表面化しやすい問題です。

タイムアウトの種類

「タイムアウト」には、いくつか種類があります。

使うライブラリによって、設定できる項目は異なります。必ず、何らかのタイムアウトを設定してください。初期値が「無制限」になっているライブラリも、あります。

値の決め方

短すぎると、正常な処理が、失敗扱いになります。長すぎると、障害の時に、自分側が固まります。

再試行してよい失敗・いけない失敗

すべての失敗を、再試行すればよいわけではありません。

サービスによって、ステータスの使い方に違いがあるため、公式の説明も確認してください(API連携が「両方正常なのに繋がらない」時の確認5項目)。

間隔の決め方:指数バックオフとジッター

再試行の間隔は、失敗するたびに、延ばしていくのが基本です。これを指数バックオフと言います。たとえば、1秒、2秒、4秒、8秒、のように、倍々に延ばします。

さらに、**ジッター(ばらつき)**を加えます。多くのクライアントが、同じタイミングで再試行すると、相手に、再び負荷が集中するためです。間隔に、ランダムな幅を持たせて、再試行のタイミングを、ずらします。

import random
import time

def wait_time(attempt, base=1.0, cap=30.0):
    # 指数バックオフ:1, 2, 4, 8... 秒(上限 cap)
    delay = min(cap, base * (2 ** attempt))
    # ジッター:0〜delay の間で、ばらつかせる
    return random.uniform(0, delay)

for attempt in range(4):
    # ... リクエストを送り、再試行すべき失敗なら:
    time.sleep(wait_time(attempt))

回数と、全体の時間に、上限を設ける

再試行には、必ず上限を設けます。

• 回数の上限:たとえば、3〜5回まで(目安)
• 全体の時間の上限:再試行を含めて、合計で何秒まで待つか(利用者を、待たせすぎないため)
• 上限に達したら、失敗として扱い、エラーを返すか、後で改めて実行する

相手が長時間不調の場合に、延々と再試行を続けるのは、避けてください。相手の復旧を、かえって妨げることがあります。

二重処理を防ぐ

再試行で、特に注意が必要なのは、決済や登録のように、繰り返すと結果が変わる操作です。タイムアウトした時点では、相手が処理を終えているかもしれません。

そのまま再試行すると、二重に処理されます。防ぐには、冪等キーのような仕組みが必要です(冪等キー(Idempotency-Key)とは、冪等性とは)。

相手を守る:続けて失敗する場合は、止める

相手が、続けて失敗を返している時に、そのまま呼び続けるのは、お互いに良くありません。一定回数、続けて失敗したら、しばらく呼び出しを止める仕組みを入れることがあります。これは、サーキットブレーカーと呼ばれる考え方です(サーキットブレーカーとは)。

AIにコードを書いてもらう時の注意

AIに、APIを呼ぶコードを頼むと、タイムアウトの設定がないコードや、失敗したら、すぐに無限に再試行するコードが、出てくることがあります。依頼する時に、条件を指定してください。

APIを呼ぶコードを書いてください。条件:①接続と応答のタイムアウトを設定する ②再試行するのは、一時的な失敗(通信エラー・429・503)のみ ③再試行は、指数バックオフ+ジッターで、最大3回 ④全体の時間にも上限を設ける ⑤APIキーは環境変数から読む

書かれたコードも、この条件が入っているかを、確認してください(AIが書いたコードをそのまま使ってはいけない理由)。

まとめ

• タイムアウトは、必ず設定する
• 再試行してよいのは、一時的な失敗。認証・入力・宛先の誤りは、再試行しない
• 間隔は、指数バックオフ+ジッター。回数と全体の時間に、上限を設ける
• 決済や登録は、冪等キーなどで、二重処理を防ぐ
• 続けて失敗する場合は、呼び出しを止める(サーキットブレーカー)

呼び出しの回数の制限については、APIをループで呼ぶ時の3つの約束もご覧ください。