Pythonのhttpxで非同期リクエストのエラーを処理!例外ハンドリングのベストプラクティス

Python httpxで非同期リクエストの例外をハンドリングするベストプラクティス解説イメージ バックエンド

Pythonで非同期にHTTPリクエストを扱うなら、httpxは現在の有力な選択肢です。
しかし同期処理と同じ感覚でawait client.get()を書いていると、思わぬところで処理全体が停止してしまう。
なぜでしょうか。

非同期コンテキストでは、例外の影響範囲が大きく異なります。
代表的な落とし穴がこちらです。

  • 一つのタイムアウトがasyncio.gather全体をキャンセルしてしまう
  • ステータスコードのエラーとネットワーク層の例外を混同してしまう
  • リトライ時にコネクションプールを枯渇させてしまう

単にtry...exceptで囲むだけでは不十分です。
どの例外をどの階層で補足し、どこで再試行し、どこで諦めるのか。
設計の指針が必要になります。

本記事では、httpx.TimeoutExceptionやRequestError、HTTPStatusErrorの住み分けから、AsyncClientの正しいライフサイクル管理、冪等性を考慮したリトライ実装まで、実務でそのまま使える例外ハンドリングのベストプラクティスを体系的に解説します。

  1. なぜhttpxの非同期処理でエラー対応が重要なのか?同期との違いから理解する
    1. 同期requestsと非同期httpxで異なる例外の伝播挙動
    2. asyncio.gatherで一つの失敗が全体を止める理由
    3. 非同期処理で無視されがちなコネクションリークのリスク
  2. httpxの例外階層を完全理解!RequestErrorとHTTPStatusErrorの違い
    1. すべての親となるRequestErrorの種類と役割
    2. TimeoutExceptionの4種類 ConnectTimeout ReadTimeout WriteTimeout PoolTimeout
    3. HTTPStatusErrorはなぜraise_for_status()が必要なのか
  3. 基本から学ぶAsyncClientの例外ハンドリング実装パターン
    1. try exceptの正しい位置 async withとawaitを分離する
    2. Python 3.11以降のExceptionGroupとTaskGroupでのエラー集約
    3. ログ出力で必ず残すべきリクエストIDとトレース情報
  4. タイムアウト設計のベストプラクティス 4つのタイムアウトを使い分ける
    1. Timeout設定のデフォルト値が危険な理由
    2. connect read write poolの適切な秒数設定とチューニング
    3. リトライ可能なタイムアウトと即時失敗すべきタイムアウトの判断
  5. 安全なリトライとサーキットブレーカー実装で安定性を高める
    1. tenacityを使った指数バックオフ付きリトライの実装例
    2. 冪等性を担保する POSTとGETでのリトライ可否の判断基準
    3. 連続失敗を防ぐサーキットブレーカー実装で安定性を高める
  6. 大量リクエストを捌く並列処理と例外の共存パターン
    1. asyncio.Semaphoreで同時接続数を制限してPoolTimeoutを防ぐ
    2. gatherとas_completedでのエラー分離処理の違い
    3. Limits設定でコネクションプールの枯渇を防ぐ方法
  7. 本番環境で差がつくログとモニタリング設計
    1. 構造化ログで例外種別とURLと経過時間を記録する
    2. OpenTelemetryでhttpxのトレースを取得する方法
  8. まとめ Python httpx非同期リクエストの例外処理ベストプラクティス総括

なぜhttpxの非同期処理でエラー対応が重要なのか?同期との違いから理解する

同期と非同期のhttpxで例外の伝播が違うことを示す概念図

同期的なrequestsに慣れていると、httpxの非同期APIも同じように例外を扱えると考えてしまいがちです。
しかし非同期I/Oでは、例外の伝播経路もリソースの寿命も根本的に異なります。
なぜ非同期ではより厳密なエラー設計が求められるのか。
その構造的な理由から整理します。

同期requestsと非同期httpxで異なる例外の伝播挙動

同期処理では、リクエストで例外が発生すればその場で呼び出し元に伝播し、try...exceptで直ちに捕捉できます。
処理の流れは単一スレッドで直線的です。

一方、httpx.AsyncClientとasyncioを組み合わせた非同期処理では、例外はイベントループを経由して伝播します。
あるコルーチンで発生したConnectTimeoutが、awaitされたタイミングで初めて呼び出し元に表面化する。
つまり、例外の発生箇所と検出箇所に時間差が生じるわけです。

この違いを整理すると以下のようになります。

観点 同期requests 非同期httpx
例外の検出 発生と同時に即時検出 await時に遅延して検出
影響範囲 当該処理のみ 同一タスクグループ全体に波及する可能性
リソース解放 withブロックで自動解放 async withの完了を待たないと解放されない

同期の常識をそのまま持ち込むと、検出の遅延と影響範囲の拡大を見落としてしまう。
これが最初の落とし穴です。

asyncio.gatherで一つの失敗が全体を止める理由

大量のリクエストを並列化する際に多用されるのがasyncio.gatherです。
ここで重要なのが、デフォルトの挙動では一つの例外が他のタスクをキャンセルするという点です。

例えば100件のリクエストをgatherで実行し、1件でReadTimeoutが発生した場合、残り99件が成功していても、全体が例外で終了します。
部分的な成功を回収できない。
結果の整合性が崩れる原因です。

これを防ぐには、設計の段階で分岐が必要です。

  • 全体の失敗を即時検知したい場合はgatherのデフォルト挙動を利用する
  • 部分的な成功を許容する場合はreturn_exceptions=Trueを指定し、結果リスト内でisinstance(r, Exception)を判定する
  • Python 3.11以降であればasyncio.TaskGroupとExceptionGroupでより構造的に集約する

どのような一貫性を担保したいのか。
仕様によって例外戦略は変わります。

非同期処理で無視されがちなコネクションリークのリスク

もう一つ、同期では起きにくいが非同期では頻発するのがコネクションリークです。
AsyncClientは内部でコネクションプールを保持しています。
例外発生時にasync withを正しく抜けられないと、プール上のコネクションがCLOSEされずに残留します。

特に以下のようなコードは危険です。

client = httpx.AsyncClient()
try:
    resp = await client.get("https://api.example.com")
except httpx.RequestError:
    pass # client.aclose()が呼ばれない

clientのaclose()が呼ばれないままループが継続すると、最終的にPoolTimeoutやToo many open filesといった二次的な障害を引き起こします。
例外処理とは、単にエラーを握りつぶすことではなく、リソースのライフサイクルを保証することでもあるのです。

だからこそ、async with httpx.AsyncClient() as client:を徹底し、例外が発生しても確実にクリーンアップされる構造を最初に作ることが、非同期httpxのベストプラクティスの出発点になります。

httpxの例外階層を完全理解!RequestErrorとHTTPStatusErrorの違い

httpxの例外クラス階層図 RequestErrorとHTTPStatusErrorの関係

httpxの例外処理で混乱が生じる最大の原因は、例外の階層を正しく把握していないことです。
すべての例外をExceptionで一括して捕捉してしまうと、リトライすべきエラーと即時失敗すべきエラーの区別がつかなくなる。
まずは体系的に整理します。

すべての親となるRequestErrorの種類と役割

httpxの例外は、httpx.HTTPErrorを頂点として大きく二つの系統に分かれます。
一つがネットワーク層の失敗を示すRequestError、もう一つがアプリケーション層の失敗を示すHTTPStatusErrorです。

RequestErrorはさらに具体的な原因に分岐します。

  • NetworkError: DNS解決失敗や接続拒否など、TCPレベルで到達できないケース
  • ProxyError: プロキシ経由時の失敗
  • UnsupportedProtocol: 未対応プロトコルへのリクエスト
  • TimeoutException: 後述するタイムアウト系の親クラス

この系統の特徴は、サーバーにリクエストが到達したかどうかが不明である点です。
つまり冪等性が担保されない限り、安易なリトライは危険を伴います。
逆に、ネットワークの一時的な揺らぎであればリトライが有効な場合もある。
区別が重要です。

TimeoutExceptionの4種類 ConnectTimeout ReadTimeout WriteTimeout PoolTimeout

タイムアウトはすべて同じではありません。
httpxではTimeoutException配下に4つの具体的な例外が用意されており、発生フェーズが明確に異なります。

例外クラス 発生フェーズ 主な原因
ConnectTimeout TCP接続確立時 サーバー停止、ファイアウォール、DNS遅延
ReadTimeout レスポンス読み取り時 サーバー側処理の遅延、巨大なボディ
WriteTimeout リクエスト送信時 アップロード帯域不足、大きなペイロード
PoolTimeout コネクション取得時 同時接続数の枯渇、Limits設定の不備

なぜ分ける必要があるのか。
リトライ戦略が変わるからです。
例えばConnectTimeoutはリトライで回復する可能性が高い一方、ReadTimeoutはサーバーが処理中である可能性を示唆するため、即時リトライは負荷を増大させるだけかもしれません。
例外種別ごとの対処を設計できる。
これがhttpxがタイムアウトを細分化している理由です。

設定側でもこの4つは個別に制御可能です。

timeout = httpx.Timeout(connect=2.0, read=10.0, write=5.0, pool=1.0)
async with httpx.AsyncClient(timeout=timeout) as client:
    await client.get("https://api.example.com/data")

一律5秒といった単一値ではなく、フェーズごとに適切な閾値を設けることが安定運用の鍵になります。

HTTPStatusErrorはなぜraise_for_status()が必要なのか

もう一つの系統であるHTTPStatusErrorは、挙動が他の例外と決定的に異なります。
httpxはデフォルトでは4xxや5xxのステータスコードを例外として扱いません。
response.status_codeが404でも500でも、await client.get()自体は正常に完了します。

これは仕様です。
REST APIによっては404を正常な分岐として扱いたいケースもあるため、ライブラリ側で勝手に例外化しない設計になっています。

例外として扱いたい場合は、明示的にraise_for_status()を呼ぶ必要があります。

resp = await client.get("https://api.example.com/users/123")
try:
    resp.raise_for_status()
except httpx.HTTPStatusError as e:
    # e.response.status_code で分岐可能
    if e.response.status_code == 404:
        return None
    raise

このメソッドを呼ぶことで初めて、ステータスコードがHTTPStatusErrorに変換され、レスポンスオブジェクトと共に捕捉できます。
RequestErrorが「届かなかった」エラーであるのに対し、HTTPStatusErrorは「届いたがサーバーがエラーを返した」エラー。
両者を混同せず、ネットワーク障害とアプリケーションエラーを明確に分離する。
それが堅牢な非同期クライアントの基本です。

基本から学ぶAsyncClientの例外ハンドリング実装パターン

AsyncClientをasync withで安全に使う例外処理パターンの図

httpxの非同期例外処理で最も重要なのは、構文の正しさではなくライフサイクルの正しさです。
どこでtry...exceptを置くかで、リソースリークの有無も、ログの精度も決まります。
基本パターンから再確認します。

try exceptの正しい位置 async withとawaitを分離する

初心者が陥りがちなのが、async withの外側で例外を捕捉してしまい、クライアントのクローズを保証できないパターンです。
正解は、クライアント生成は外側、リクエストと例外処理は内側に置くことです。

async withがコンテキストを管理し、その内部で発生した例外だけをハンドリングする。
こうすることで、どのような例外が発生してもaclose()が確実に呼ばれます。

async with httpx.AsyncClient() as client:
    try:
        resp = await client.get("https://api.example.com/items")
        resp.raise_for_status()
    except httpx.TimeoutException:
        # タイムアウトは一時的な問題としてリトライ候補に
        logger.warning("timeout", extra={"url": str(resp.url) if 'resp' in locals() else url})
        raise
    except httpx.HTTPStatusError as e:
        # ステータスエラーはアプリケーションロジックで分岐
        if e.response.status_code >= 500:
            raise
        return None

tryのスコープを最小化するのがポイントです。
AsyncClientの生成まで含めてしまうと、生成時の失敗とリクエスト時の失敗を区別できなくなります。
責務の分離。
例外処理の基本です。

Python 3.11以降のExceptionGroupとTaskGroupでのエラー集約

asyncio.gather(return_exceptions=True)は部分的な成功を扱えますが、戻り値の型がlist[Response | Exception]となり、型安全性が低下します。
Python 3.11で導入されたTaskGroupとExceptionGroupは、この問題をより構造的に解決します。

TaskGroupでは、複数のタスク内で発生した例外が自動的にExceptionGroupに集約され、コンテキストを抜けるタイミングで一括して送出されます。
個別のタスクは独立して実行され、一つの失敗が他を即座にキャンセルしない。
より制御しやすい並列実行です。

import asyncio

async def fetch(client, url):
    resp = await client.get(url)
    resp.raise_for_status()
    return resp.json()

async with httpx.AsyncClient() as client:
    async with asyncio.TaskGroup() as tg:
        t1 = tg.create_task(fetch(client, "https://api.example.com/a"))
        t2 = tg.create_task(fetch(client, "https://api.example.com/b"))

# TaskGroupを抜けた後、t1.result() t2.result()で結果を取得
# 失敗があれば ExceptionGroup として集約される

except*構文で例外種別ごとに分岐できるため、TimeoutExceptionだけをリトライ対象にするといったフィルタリングが型安全に行えます。
本番の並列処理では、こちらの採用を強く推奨します。

ログ出力で必ず残すべきリクエストIDとトレース情報

非同期処理のデバッグで最も困るのが、「どのリクエストが、なぜ失敗したのか」が追跡できないことです。
例外メッセージだけをログに残しても、再現性がありません。
最低限、以下の情報を構造化して残します。

項目 内容 取得方法
url リクエストURL request.url
method HTTPメソッド request.method
elapsed 経過時間 time.perf_counter()で計測
exception_type 例外クラス名 type(e).__name__
trace_id 分散トレーシングID X-Request-IDヘッダやOTelから付与

特にelapsedは重要です。
ConnectTimeoutなのかReadTimeoutなのかを事後的に判断する手がかりになります。
単なる文字列ログではなく、構造化ログとしてJSONで出力し、監視基盤でフィルタ可能にしておく。
これだけで障害時の平均復旧時間は大きく変わります。
例外処理は、未来の自分への情報提供でもあるのです。

タイムアウト設計のベストプラクティス 4つのタイムアウトを使い分ける

httpxのTimeout設定 4種類のタイムアウトを使い分ける設計図

タイムアウト設定は、非同期クライアントの安定性を左右する最も重要なパラメータです。
単一の秒数で全てを制御しようとすると、必ずどこかに歪みが生じます。
httpxが4つのタイムアウトに分割している意図を理解し、適切に使い分ける必要があります。

Timeout設定のデフォルト値が危険な理由

httpx.AsyncClientのデフォルトタイムアウトはTimeout(timeout=5.0)、つまり全フェーズ一律5秒です。
一見安全に見えますが、実運用では二つの問題を抱えます。

一つは、接続確立に5秒も待ってしまう点です。
通常、TCPハンドシェイクは数十ミリ秒で完了すべき処理です。
5秒待つということは、DNS障害やファイアウォールによるドロップを検知するまでに無駄な時間を費やすことになります。
結果、リトライの開始が遅れ、ユーザー体感のレイテンシが悪化します。

もう一つは、逆に読み取りが5秒で打ち切られる点です。
レポート生成や大量データの取得など、正当に10秒以上かかるAPIも存在します。
デフォルトのままでは、正常なリクエストまでReadTimeoutとして失敗させてしまう。
デフォルト値は開発用のセーフティネットであり、本番の仕様ではないのです。

connect read write poolの適切な秒数設定とチューニング

4つのタイムアウトは、それぞれ責務が異なります。
推奨される考え方は以下の通りです。

  • connect: 短く。2秒以内が目安です。接続できない相手を長く待つ意味はありません
  • read: APIの特性に合わせる。高速なCRUDなら5秒、集計系なら30秒など、可変にします
  • write: アップロードサイズに依存します。通常は5〜10秒で十分です
  • pool: 最も短く。0.5〜1.0秒です。プールが枯渇している状態は、既に過負荷のサインです

実装では、クライアントのデフォルトとリクエストごとの上書きを組み合わせます。

# クライアントは厳しめのデフォルトを設定
default_timeout = httpx.Timeout(connect=1.0, read=5.0, write=5.0, pool=0.5)
client = httpx.AsyncClient(timeout=default_timeout)

# 時間がかかるエンドポイントだけ個別に緩和
slow_timeout = httpx.Timeout(connect=1.0, read=30.0, write=10.0, pool=0.5)
resp = await client.get("https://api.example.com/report", timeout=slow_timeout)

このようにデフォルトは厳しく、例外的に緩める設計にすることで、意図しない長時間ブロッキングを防げます。

リトライ可能なタイムアウトと即時失敗すべきタイムアウトの判断

すべてのタイムアウトをリトライすべきではありません。
判断基準は、サーバー側で処理が開始された可能性があるかどうかです。

タイムアウト種別 リトライ可否 理由
ConnectTimeout リトライ推奨 サーバーに到達していないため冪等性は保たれる
PoolTimeout リトライ慎重に クライアント側の過負荷が原因、即時リトライは悪化させる
WriteTimeout リトライ非推奨 送信途中で切断、サーバー側で重複処理される恐れ
ReadTimeout 条件付きでリトライ GETなら可、POSTならサーバー処理中の可能性を考慮する

特にReadTimeoutは注意が必要です。
サーバーが処理を完了し、レスポンスを返している最中にタイムアウトした場合、リトライすると二重登録や二重課金につながりかねません。
GETのような冪等なメソッドはリトライ、POSTやPATCHはリトライしない。
この原則をタイムアウト種別と組み合わせて判断することが、堅牢な非同期システムの核心になります。

安全なリトライとサーキットブレーカー実装で安定性を高める

リトライとサーキットブレーカーでhttpxの安定性を高める構成図

非同期リクエストの例外処理で、単に失敗を検知するだけではシステムは安定しません。
重要なのは、失敗からどう回復するかを設計することです。
リトライとサーキットブレーカーは、そのための二つの車輪です。

tenacityを使った指数バックオフ付きリトライの実装例

安易な即時リトライは、障害発生時にサーバーへの負荷を倍増させ、リトライストームを引き起こします。
これを防ぐ定石が指数バックオフとジッターです。
tenacityライブラリを用いると、宣言的に実装できます。

リトライ対象はTimeoutExceptionとNetworkError、そして5xxのHTTPStatusErrorに限定します。
4xxはクライアント側の誤りなのでリトライしても回復しません。

from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception_type
import httpx

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential_jitter(initial=0.5, max=5.0),
    retry=retry_if_exception_type((httpx.TimeoutException, httpx.NetworkError)),
    reraise=True
)
async def resilient_get(client: httpx.AsyncClient, url: str):
    resp = await client.get(url)
    resp.raise_for_status()
    return resp

wait_exponential_jitterがポイントです。
待機時間が0.5秒、1秒、2秒と指数関数的に伸び、さらにランダムなジッターが加わることで、複数クライアントが同時にリトライするサンダーハーディング問題を回避できます。
reraise=Trueで最終的な失敗は呼び出し元に伝播させ、握りつぶさない。
これが堅牢なリトライの基本形です。

冪等性を担保する POSTとGETでのリトライ可否の判断基準

リトライを実装する上で最も慎重になるべき概念が冪等性です。
同じリクエストを何度送っても結果が変わらない性質を指します。

メソッド 冪等性 リトライ可否 判断理由
GET あり リトライ可 読み取りのみで副作用なし
PUT あり リトライ可 同じ内容で上書きするため結果は同一
DELETE あり 条件付きで可 2回目は404になるが副作用は変わらない
POST なし 原則不可 都度新規作成され二重登録の危険
PATCH なし 原則不可 部分更新の重複で状態が不定になる

POSTでReadTimeoutが発生した場合、サーバー側では処理が成功している可能性があります。
ここでリトライすると、注文の二重作成や決済の二重課金につながりかねません。
POSTをリトライする必要がある場合は、Idempotency-Keyヘッダを付与し、サーバー側で重複排除を実装することが前提になります。
クライアント側だけで解決できる問題ではないのです。

連続失敗を防ぐサーキットブレーカー実装で安定性を高める

リトライが単発の失敗に対する対策であるのに対し、サーキットブレーカーは連続的な失敗に対する対策です。
APIがダウンしているのにリトライを繰り返しても、復旧を遅らせるだけです。

サーキットブレーカーは3つの状態を持ちます。

  • Closed: 正常状態。リクエストを通過させる
  • Open: 障害検知状態。一定期間リクエストを即時失敗させ、サーバーを休ませる
  • Half-Open: 回復確認状態。試しに1件だけ通し、成功すればClosedに戻す

Pythonではpybreakerやaiobreakerを用いて実装できます。

import pybreaker

breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=30)

@breaker
async def call_external_api(client, url):
    resp = await client.get(url, timeout=httpx.Timeout(connect=1.0, read=3.0))
    resp.raise_for_status()
    return resp.json()

5回連続で失敗したら30秒間サーキットをオープンにする。
こうすることで、障害発生時に自システムが自律的に負荷を遮断し、相手システムの復旧を待つことができる。
リトライが「諦めずに再挑戦する」仕組みであるのに対し、サーキットブレーカーは「潔く諦めて全体を守る」仕組みです。
両者を組み合わせて初めて、本番環境に耐える非同期クライアントが完成します。

大量リクエストを捌く並列処理と例外の共存パターン

大量の非同期リクエストを並列処理しつつ例外を分離するイメージ

非同期の真価は、数百件のリクエストを同時に捌くスループットにあります。
しかし制御なく並列度を上げると、PoolTimeoutやメモリ枯渇を招き、例外処理自体が破綻します。
並列度を制限しつつ、失敗を分離する。
この両立が鍵になります。

asyncio.Semaphoreで同時接続数を制限してPoolTimeoutを防ぐ

httpx.AsyncClientは内部でコネクションプールを持ちますが、asyncio側で無制限にタスクを生成すると、プールの獲得待ちが発生しPoolTimeoutになります。
これを防ぐ最もシンプルな方法がasyncio.Semaphoreです。

セマフォは、同時に実行可能なタスク数に上限を設ける仕組みです。
プールのサイズと連動させることで、待ち行列をクライアント側で制御できます。

import asyncio
import httpx

sem = asyncio.Semaphore(20) # 同時20件までに制限

async def bounded_fetch(client: httpx.AsyncClient, url: str):
    async with sem:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.json()

async def main(urls: list[str]):
    async with httpx.AsyncClient() as client:
        tasks = [bounded_fetch(client, u) for u in urls]
        results = await asyncio.gather(*tasks, return_exceptions=True)
        return results

セマフォをclient.getの直前で獲得することで、コネクションを実際に必要とする瞬間だけ並列度を制限できます。
単にgatherに1000件投げるのではなく、実行中のタスク数を常に可視化・制御する。
これが大量リクエストの基本です。

gatherとas_completedでのエラー分離処理の違い

並列実行時の例外処理には、二つの代表的なパターンがあります。

gather(return_exceptions=True)は、すべてのタスクが完了するまで待ち、結果をリストで一括して返します。
成功したレスポンスと例外オブジェクトが混在するため、後段でisinstanceによる分岐が必要です。
全体の成否を集計したいバッチ処理に向いています。

一方、asyncio.as_completedは、完了したタスクから逐次的に結果を返します。
失敗したタスクがあっても、他のタスクの完了を待たずに処理を進められる。
ストリーミング的に結果を処理したい場合に有効です。

for coro in asyncio.as_completed(tasks):
    try:
        data = await coro
        # 成功時の処理を即時実行
        await save(data)
    except httpx.HTTPStatusError as e:
        # 失敗はその場でログ化し、全体は継続
        logger.error("fetch failed", extra={"status": e.response.status_code})

gatherが一括集計型であるのに対し、as_completedは逐次処理型です。
どちらを選ぶかは、失敗時に即時対応が必要か、後でまとめてリカバリすれば良いかという要件で決まります。

Limits設定でコネクションプールの枯渇を防ぐ方法

セマフォがasyncio側の制御であるのに対し、httpx側でもプールサイズを明示的に制御できます。
それがLimitsオブジェクトです。

パラメータ 意味 推奨設定
max_keepalive_connections キープアライブする最大接続数 同時実行数と同程度、例: 20
max_connections 全体の最大接続数 keepaliveより少し大きめ、例: 50
keepalive_expiry キープアライブの有効期限 デフォルトの5秒で十分な場合が多い

デフォルトではmax_keepalive_connections=20、max_connections=100です。
セマフォを20に設定しているのにmax_connectionsが10では、セマフォをすり抜けてもプールでブロックされます。
両者の整合性を取る必要があります。

limits = httpx.Limits(max_keepalive_connections=20, max_connections=50)
async with httpx.AsyncClient(limits=limits, timeout=httpx.Timeout(pool=0.5)) as client:
    # poolタイムアウトを短くし、枯渇を早期検知
   ...

poolタイムアウトを0.5秒のように短く設定することで、枯渇が発生した際に長時間待機せず、すぐにPoolTimeoutとして検知できます。
検知できれば、セマフォの値を下げる、Limitsを上げるといったチューニングが可能になる。
観測可能性を確保するために、あえて厳しい設定にする。
これもまた、堅牢な並列処理の設計原則です。

本番環境で差がつくログとモニタリング設計

本番環境のhttpxエラーを可視化するログとモニタリングのダッシュボード

開発環境ではprint(e)でも十分ですが、本番環境で非同期リクエストが失敗した際、その一行では何もわかりません。
どのURLで、どのフェーズで、何秒待って失敗したのか。
再現可能なログとトレースがなければ、障害対応は勘に頼ることになります。
運用で差がつく設計を解説します。

構造化ログで例外種別とURLと経過時間を記録する

非同期処理のログで最も避けるべきは、文字列結合による非構造な出力です。
f"failed: {url} {e}"のようなログは、監視基盤で集計できません。
構造化ログとしてJSONで出力し、フィールドごとに検索可能にする必要があります。

最低限含めるべき項目は、例外の種別、リクエスト情報、計測情報の3つです。

import time
import logging
import httpx
from pythonjsonlogger import jsonlogger

logger = logging.getLogger("httpx_client")

async def logged_fetch(client: httpx.AsyncClient, url: str):
    start = time.perf_counter()
    try:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp
    except httpx.HTTPError as e:
        elapsed = time.perf_counter() - start
        logger.error(
            "http request failed",
            extra={
                "url": url,
                "method": "GET",
                "elapsed_ms": int(elapsed * 1000),
                "exception_type": type(e).__name__,
                "status_code": getattr(e.response, "status_code", None) if isinstance(e, httpx.HTTPStatusError) else None,
            },
        )
        raise

elapsed_msが重要です。
ConnectTimeoutであれば数十ms、ReadTimeoutであれば設定したreadタイムアウトに近い値になります。
ログを見ただけで、どのフェーズで失敗したか推定できる。
障害時の平均検知時間は、ログの質で決まります。

また、urlはクエリパラメータを含めると個人情報漏洩のリスクがあるため、パス部分のみを記録する、あるいはマスキング処理を入れる配慮も必要です。

OpenTelemetryでhttpxのトレースを取得する方法

ログが単一リクエストの記録であるのに対し、トレースは分散システム全体でのリクエストの旅路を記録します。
httpxはOpenTelemetryとの親和性が高く、数行で自動計装できます。

opentelemetry-instrumentation-httpxを導入すると、AsyncClientの各リクエストにtrace_idとspan_idが自動付与され、connectやreadの時間がスパンとして可視化されます。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

trace.set_tracer_provider(TracerProvider())
tracer_provider = trace.get_tracer_provider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

HTTPXClientInstrumentor().instrument()

# 以降の httpx.AsyncClient のリクエストは自動でトレースされる

これにより、Grafana TempoやJaeger上で以下のような分析が可能になります。

  • どのドメインへのリクエストでレイテンシが増大しているか
  • リトライが発生した際に、どの試行で成功したか
  • 特定のtrace_idに紐づく一連の非同期呼び出しの依存関係

ログが「点」の情報であるのに対し、トレースは「線」の情報です。
特にマイクロサービス間でhttpxを用いて多数のAPIを呼び出す構成では、トレースがないとボトルネックの特定は不可能に近い。
構造化ログで例外を確実に記録し、OpenTelemetryで全体の流れを可視化する。
この二層の監視設計が、本番環境での安定運用を支えます。

まとめ Python httpx非同期リクエストの例外処理ベストプラクティス総括

Python httpxの非同期例外処理ベストプラクティスまとめのイメージ

本記事では、httpxの非同期リクエストにおける例外処理を、階層の理解から実装パターン、運用設計まで一貫して解説してきました。
最後に、実務でそのまま適用できるベストプラクティスを総括します。

非同期の例外処理が難しい理由は、失敗の影響が局所的でなくなる点にあります。
同期処理では一つのリクエストの失敗はその処理だけで完結しますが、非同期ではgatherやTaskGroupを通じて他のタスクに波及し、コネクションプールの枯渇という二次障害まで引き起こします。
だからこそ、例外を「握りつぶす」のではなく「設計する」姿勢が求められるのです。

本記事で紹介した原則を、実装チェックリストとして整理します。

  • 例外階層を正しく分離する: RequestErrorはネットワーク層、HTTPStatusErrorはアプリケーション層として区別し、except Exceptionでの一括捕捉を避ける
  • タイムアウトは4つに分割して設計する: connectは短く1秒、readはAPI特性に合わせて可変に、poolは0.5秒と厳しめに設定し、早期に過負荷を検知する
  • クライアントのライフサイクルを保証する: async with httpx.AsyncClient()を徹底し、try...exceptはその内側に限定する。リソースリークは二次障害の元です
  • リトライは冪等性を前提にする: GETはリトライ可、POSTは原則不可。リトライする場合は指数バックオフとジッターを必須とし、tenacityなどで宣言的に実装する
  • 並列度は二重で制御する: asyncio.Semaphoreでタスク数を、httpx.Limitsでコネクション数を制限し、両者の整合性を取る
  • 失敗を観測可能にする: 構造化ログでurl、elapsed_ms、exception_typeをJSON出力し、OpenTelemetryで分散トレースを取得する

これらをすべて満たす、本番想定の最小構成がこちらです。

import httpx
import asyncio
from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception_type

limits = httpx.Limits(max_keepalive_connections=20, max_connections=50)
timeout = httpx.Timeout(connect=1.0, read=5.0, write=5.0, pool=0.5)
sem = asyncio.Semaphore(20)

@retry(stop=stop_after_attempt(3), wait=wait_exponential_jitter(0.5, 5), retry=retry_if_exception_type((httpx.TimeoutException, httpx.NetworkError)), reraise=True)
async def safe_fetch(client: httpx.AsyncClient, url: str):
    async with sem:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.json()

async def run(urls: list[str]):
    async with httpx.AsyncClient(limits=limits, timeout=timeout) as client:
        async with asyncio.TaskGroup() as tg:
            tasks = [tg.create_task(safe_fetch(client, u)) for u in urls]
    return [t.result() for t in tasks]

このコードには、本記事で述べたすべての要素が含まれています。
厳しめのタイムアウト、セマフォとLimitsによる二重の並列度制御、指数バックオフ付きリトライ、TaskGroupによる構造的なエラー集約、そしてasync withによる確実なクリーンアップ。
単なるサンプルではなく、本番投入の出発点として使えるはずです。

例外処理は、エラーが起きた後に考えるものではありません。
どのような失敗を許容し、どのように回復し、何を記録するのか。
リクエストを書く前に設計しておくことで、非同期システムは初めて安定します。

本記事の内容をベースに、ご自身のAPI特性に合わせたチューニングを進めてみてください。
堅牢な非同期クライアントは、サービスの信頼性を支える土台になります。

コメント

タイトルとURLをコピーしました