エラー処理の設計:例外・リトライ・タイムアウトの考え方

開発2026年11月17日公開読了目安 約8分

目次
  1. エラー処理の基本方針
  2. 例外の扱い方
  3. タイムアウトの設計
  4. リトライの設計
  5. 運用で気を付けたいポイント
  6. まとめ

外部APIやデータベースを使うシステムでは、通信の失敗や遅延は、避けられないものとして設計する必要があります。
その場面で、例外を握りつぶしたり、無制限に待ち続けたり、失敗のたびに再送を繰り返したりすると、小さな障害が全体の停止につながります。
この記事では、例外の扱い方、リトライの条件、タイムアウトの決め方を整理します。
コード例はPythonですが、考え方は言語を問いません。

エラー処理の基本方針

エラー処理で最初に決めるのは、「その失敗を、どこで、誰が扱うか」です。
次の3つを分けて考えると、設計が整理しやすくなります。

  • 回復できるエラー:一時的な通信断のように、リトライで解決する可能性がある。
  • 回復できないエラー:入力値の誤りや権限不足のように、何度やっても同じ結果になる。
  • 想定外のエラー:バグや設定ミスのように、早く気づいて直すことが目的になる。

回復できるエラーだけをリトライし、残りは呼び出し元に伝えるか、記録して止めます。
この区別がないと、直らないエラーを延々とリトライすることになります。

例外の扱い方

捕まえる範囲を絞る

except Exception や、例外の種類を指定しない except: は、想定していない不具合まで隠してしまいます。
捕まえるのは、対処できる例外に限ります。
次の例は、例外の種類ごとに分けて捕まえる書き方の骨組みです。

import json
from urllib.error import HTTPError, URLError
from urllib.request import urlopen

def fetch_json(url: str) -> dict:
    try:
        with urlopen(url, timeout=5) as res:
            return json.load(res)
    except HTTPError:
        # サーバーが応答を返し、エラーのステータスだった
        # ここではログ記録などを入れる想定
        raise
    except (URLError, TimeoutError):
        # 接続できない、または時間内に応答がなかった
        # ここではログ記録などを入れる想定
        raise

HTTPError は URLError のサブクラスです。
そのため、範囲の狭い HTTPError を先に書きます。
なお、この記事のコードはPython 3.10以降を前提としています。
Python 3.10で、ソケットのタイムアウトを表す socket.timeout が TimeoutError の別名になったため、TimeoutError で捕まえられます。

握りつぶさず、原因を保つ

例外を別の例外に変換するときは、raise ... from e を使うと、元の原因が追えます。
業務上の意味を持つ例外(たとえば UpstreamUnavailable)に変換しておくと、呼び出し側は通信ライブラリの詳細を知らずに済みます。

次の例では、fetch_json の中で、リトライしてよい失敗だけを UpstreamUnavailable に変換します。
HTTPError も URLError の一種なので、先に捕まえて、ステータスで振り分けます。

import json
from urllib.error import HTTPError, URLError
from urllib.request import urlopen

RETRYABLE_STATUS = {429, 503}

class UpstreamUnavailable(Exception):
    """外部サービスが一時的に使えない"""

def fetch_json(url: str) -> dict:
    try:
        with urlopen(url, timeout=5) as res:
            return json.load(res)
    except HTTPError as e:
        if e.code in RETRYABLE_STATUS:
            raise UpstreamUnavailable(url) from e
        raise  # 400や404などは、そのまま伝える
    except (URLError, TimeoutError) as e:
        raise UpstreamUnavailable(url) from e

URLError を先に書くと、400や404も UpstreamUnavailable に変わり、リトライの対象になってしまいます。

ログには、スタックトレースを含めて記録します。
一方、利用者に返す応答には、スタックトレースや内部のSQLを含めません。

タイムアウトの設計

Pythonの urlopen は、timeout を指定しないと、グローバルな既定値に従います。
この既定値は、通常は設定されておらず、応答を無期限に待つ可能性があります。
応答が返らない通信に、スレッドやワーカーが占有され続けると、処理待ちが積み上がります。
外部への通信には、必ず上限時間を指定します。

決め方の目安は次のとおりです。

観点 考え方
接続と読み取りを分ける(ライブラリが対応する場合) 接続は短く、読み取りは処理内容に応じて長めにする
呼び出し元の制限より短くする 自分のAPIに30秒の制限があるなら、内部の通信はそれより短くする
実測に基づく 通常の応答時間を計測し、余裕を持たせた値にする

リトライを入れる場合は、全体の所要時間にも注意が必要です。
1回5秒のタイムアウトで4回試すと、通信だけで最悪20秒かかり、待ち時間を加えると最大で約23.5秒になります(後述の with_retry の値で計算しています)。
呼び出し元の制限を超えないよう、全体の期限も決めておきます。

リトライの設計

リトライしてよい条件

リトライは、「もう一度やれば成功する可能性があり、かつ重複して実行しても安全」な場合に限ります。

  • 対象にしやすい:タイムアウト、接続エラー、HTTPの503、429(Retry-After ヘッダーで待ち時間が示されることがある)。
  • 対象にしない:400や404など、リクエストを直さない限り同じ結果になるエラー。
  • 注意が必要:POSTによる決済や登録など、再送すると二重に実行される処理。

冪等(べきとう)とは、同じ操作を何回行っても結果が同じになる性質のことです。
二重実行が問題になる処理は、リクエストごとに一意のID(冪等キー)を付けて、サーバー側で重複を判定できるようにしてから、リトライします。

待ち時間を増やし、ばらつかせる

失敗の直後に即座に再送すると、障害中のサーバーへ負荷を重ねます。
待ち時間を指数的に増やす「指数バックオフ」に、ランダムな揺らぎ(ジッター)を加えるのが一般的です。
ジッターがないと、多数のクライアントが同じ時刻に再送し、負荷が集中します。

import random
import time

def with_retry(func, max_attempts=4, base=0.5, cap=8.0):
    for attempt in range(1, max_attempts + 1):
        try:
            return func()
        except UpstreamUnavailable:
            if attempt == max_attempts:
                raise  # 回数の上限に達したら、呼び出し元に伝える
            wait = min(cap, base * 2 ** (attempt - 1))
            time.sleep(random.uniform(0, wait))

この例では、待ち時間の上限が0.5秒、1秒、2秒と増えます。
試行の回数を増やした場合も、cap により8秒を超えません。
実際の待ちは、0秒から上限までの間でランダムに決まります。
サーバーが Retry-After で待ち時間を示した場合は、その指示を優先します(例では省略しています)。

呼び出し側では data = with_retry(lambda: fetch_json(url)) のように使います。
fetch_json が400や404をそのまま送出するため、これらはリトライされません。

運用で気を付けたいポイント

ここまでの設計を本番で生かすには、上限と記録の仕組みも合わせて用意します。

  • リトライの回数と全体の期限に上限を置き、無制限のリトライで障害を長引かせないようにする。
  • リトライが起きたことをログに残す(成功していても、頻発するなら相手の不調や設定の誤りの兆候になる)。
  • エラーを握りつぶさず、最終的には監視や通知で人が気づける形にする。

失敗が続く相手には、リトライを重ねるより、一定期間は呼び出し自体を止めるほうが、相手の回復を妨げません。
この仕組みをサーキットブレーカーと呼びます。
また、時間のかかる処理は、リクエストの中で再試行せず、ジョブキューに預けて非同期で再実行する設計も選べます。
利用者を待たせずに済み、リトライの間隔も長く取れます。

まとめ

エラー処理の設計は、失敗を「回復できるもの」と「できないもの」に分け、前者にだけ上限付きのリトライを適用することが出発点です。
例外は、対処できる範囲に絞って捕まえ、原因を保ったまま上位に伝えます。
外部への通信にはタイムアウトを設定し、リトライの待ち時間には指数バックオフとジッターを使います。
まずは、いま使っている外部通信に、タイムアウトの指定漏れがないかを確認するところから始めてみてください。

参考資料・出典

コラム一覧を見る »