OpenAI API 接続エラー: APIConnectionError はまず経路から切り分ける

openai.APIConnectionError: Connection error. が出たら、失敗したアプリと同じプロセスで、実際の接続先と元の例外を確認してください。 DNS、TLSの証明書検証、プロキシ、外向き通信の許可に問題があれば、その設定を直します。HTTPの401や429が返っている場合は、認証や利用枠の確認へ進みます。エラー名だけを見てAPIキーを作り直すより、この分岐を先に確かめるほうが修正先を絞れます。

APIConnectionError は、SDKが接続や通信に失敗したときの例外です。OpenAIの公式エラーガイドは、ネットワーク、プロキシ、SSL証明書、ファイアウォール、コンテナの権限を確認するよう案内しています。ただし、応答やリクエストIDが手元にないことは、サーバーが要求を受け取っていない証明にはなりません。送信後に応答を失った場合もあるため、再送の判断は切り分けと分けて行います。

最初の切り分け：HTTP応答があるかを確かめる

最初に残すのは、発生時刻、接続先のホスト、例外名、HTTPステータスの有無、取得できたリクエストIDです。接続先は設定ファイルのつもりではなく、失敗したクライアントが実際に使っている値を確認します。APIキー、認証ヘッダー、プロンプト全文をログに出す必要はありません。

Pythonでは、応答の4xx／5xxは APIStatusError 系の例外で、status_code と response を確認できます。タイムアウトは APITimeoutError で、APIConnectionError の派生です。Nodeでは接続タイムアウトが APIConnectionTimeoutError になります。分類は2026年10月6日に確認したPythonリファレンスとTypeScriptリファレンスに基づきます。独自のHTTPクライアントやフックが投げた例外は、そのまま伝わる場合もあります。

429が返ったら、送信量によるレート制限の切り分けを使います。本文に insufficient_quota や課金関連の詳細コードがあれば、残高・支出上限・承認済み利用枠の確認へ進んでください。接続エラーの再試行だけでは、これらの設定は直りません。

ブラウザではなく、失敗したプロセスで調べる

ブラウザでOpenAIのサイトを開けても、Pythonの証明書ストア、Nodeの fetch、コンテナの外向き通信が同じとは限りません。ローカルで成功し、本番だけ失敗する場合は、本番のコンテナや関数、リージョン、クライアント設定を対象にします。

比較する項目は、接続先のホストとAPIのパス、SDK・HTTPライブラリのバージョン、プロキシの使用有無、信頼するCA、接続・読み取りのタイムアウト、再試行回数です。キーの値を並べる代わりに、キーの管理名や所属プロジェクトが一致するかを確認します。プロキシURLに認証情報がある場合も、その値を公開ログへ出さないでください。

Python：既存クライアントの例外を同じ場所で捕捉する

次の関数は、既存アプリの非ストリーミングの操作を1回実行するための診断用部品です。クライアントを別に作り直さず、既存のHTTP設定を使った操作を渡します。タイムアウトを先に捕捉し、元の例外の型を __cause__ からたどります。戻り値の記録には応答本文や秘密値を入れません。

import time
import uuid
import openai


def cause_types(error):
    names = []
    seen = set()
    current = error.__cause__
    while current is not None and id(current) not in seen:
        seen.add(id(current))
        names.append(type(current).__name__)
        current = current.__cause__
    return names


def diagnose_once(operation):
    client_request_id = "diag-" + uuid.uuid4().hex
    started = time.monotonic()
    record = {"client_request_id": client_request_id}
    result = None
    try:
        result = operation(client_request_id)
        record.update(
            kind="response",
            request_id=getattr(result, "_request_id", None),
        )
    except openai.APITimeoutError as error:
        record.update(kind="timeout", causes=cause_types(error))
    except openai.APIConnectionError as error:
        record.update(kind="connection", causes=cause_types(error))
    except openai.APIStatusError as error:
        record.update(
            kind="http_error",
            status=error.status_code,
            request_id=error.request_id,
        )
    record["elapsed_seconds"] = round(time.monotonic() - started, 3)
    return result, record

呼び出し部分は、既存の client と、そのプロジェクトで利用可能な model_id を使って次のように組み込みます。両変数はアプリ側で準備済みであることが前提です。これは実際の生成要求で、成功すれば通常のAPI利用料金が発生し得ます。 実行前に接続先と再送の可否を確認してください。

result, record = diagnose_once(
    lambda client_request_id: client.with_options(
        max_retries=0,
        timeout=30.0,
    ).responses.create(
        model=model_id,
        input="Reply with OK.",
        extra_headers={"X-Client-Request-Id": client_request_id},
    )
)
print(record)

max_retries=0 は診断中の送信回数を分かりやすくする設定です。30秒はこの小さい確認要求の例で、長い生成に共通する推奨値ではありません。Pythonの数値タイムアウトは秒単位です。with_options で既存クライアントの接続設定を保ち、要求ごとに再試行と期限を指定する方法は公式Pythonリファレンスを参照してください。

kind=connection なら causes に出た例外の型と、社内で安全に扱える元のエラー詳細を照合します。たとえば名前解決、証明書検証、プロキシ接続のどこで失敗したかが分かれば、次節の対応へ進めます。型名だけで原因が分からない場合は、タイムスタンプをネットワークやプロキシのログと合わせます。kind=response はこの1件の応答を取得したという意味で、元の大量処理まで復旧した証明ではありません。

curlは同じ環境の経路確認に使う

コンテナ内などで、認証なしのHTTPS応答を確かめる補助確認にはcurlを使えます。OpenAIへ直接接続する場合の例は次のとおりです。Azureやゲートウェイを使っている場合は、提供元が許可する確認用URLに変更します。未知のホストへキーを送らないでください。

TARGET_URL='https://api.openai.com/v1/models'
curl -q --silent --show-error \
  --connect-timeout 5 --max-time 15 \
  --output /dev/null \
  --write-out 'http=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n' \
  "$TARGET_URL"
curl_exit=$?
printf 'curl_exit=%s\n' "$curl_exit"

-q はcurlの最初の引数に置き、既定のcurl設定ファイルを読み込ませません。プロキシの環境変数は無効にしないため、実際にどの経路を使うかは確認が必要です。このコマンドはTLS検証を維持し、APIキーも生成要求も送信しません。--connect-timeout は名前解決と接続・TLS確立を含む段階、--max-time は全体の上限です。curlの公式マニュアルで各オプションと終了コードを確認できます。

HTTPステータスとcurlの終了コードは別です。この例では --fail を使わないため、401や503でもcurlが終了コード0を返すことがあります。http=000 は確認中にHTTPステータスを得られなかったという意味で、元の生成要求が未処理だった証拠ではありません。

また、curlが成功してSDKが失敗するなら、SDKのCA・プロキシ・HTTP実装を比較します。curlの確認だけでは、アプリの認証、モデルへのアクセス、生成成功は確認できません。

原因に合った設定を直す

社内ネットワークで証明書検証に失敗する

社内のHTTPS検査プロキシがある場合、ブラウザが信頼する会社のCAを、PythonやNodeのHTTPクライアントが信頼していないことがあります。まず、表示された証明書の発行者と会社のネットワーク構成を担当者に確認します。会社が指定したCAファイルと設定方法を入手し、実際に失敗したHTTPクライアントの信頼設定へ追加してください。

日本語のQiita記事「OpenAI API利用時のSSLErrorに対して証明書をダウンロードして解決する」は、業務PCのプロキシと証明書検証の具体例を扱っています。ただし、2023年公開・2025年更新の手順に出てくるcertifiの直接編集や REQUESTS_CA_BUNDLE を、現在のOpenAI SDKへそのまま当てはめないでください。requests向けの設定と、現在のSDKが使うHTTPライブラリの設定は区別が必要です。

2026年10月6日に確認したPythonリファレンスでは、HTTPX2と DefaultHttpx2Client を使う構成が案内されています。インストール済みの旧版がHTTPXを使う場合は、その版の対応するクライアント設定を使います。現在の構成なら、会社指定CAを読み込んだ検証有効の SSLContext を用意し、対応するHTTPクライアントの verify に渡す方法があります。ファイルの存在、コンテナからの読み取り権限、証明書の更新状態も確認します。

検証を無効にする、ブラウザから取った証明書を根拠なく信頼する、SDKのインストール先を直接書き換える、といった対応は避けます。修正後、同じプロセスで証明書検証が成功し、小さいAPI要求の応答が取得できることを確認すれば、変更したCA設定の効果を判断できます。

プロキシが必要なのに、SDKだけ通らない

端末のプロキシ設定や HTTPS_PROXY が、すべてのHTTP実装に同じように引き継がれるとは限りません。まず実際のクライアントが、会社指定のプロキシを使っているかを確認します。必要なら、そのSDK版とHTTPライブラリが対応する公開の設定方法でプロキシを指定します。

Nodeの場合は、プロキシ設定と fetch 実装の組み合わせが重要です。現行のTypeScriptリファレンスのNode例は、undiciの fetch と ProxyAgent を組み合わせ、対応する fetchOptions の dispatcher を渡します。別の fetch にundici専用の dispatcher だけを付けても、その設定を扱えるとは限りません。SDKに独自 fetch を渡しているなら、その実装を含めて確認してください。

Bunでは proxy、Denoでは createHttpClient とクライアントを使う構成など、実行環境で方法が異なります。古い記事の httpAgent をどの環境にも共通の修正として貼り付けず、実行中の環境とSDK版に対応する方法を選びます。認証付きプロキシは認証失敗や接続許可も確認し、通信禁止や地域制限を別経路で回避する対応にはしません。

本番コンテナだけ失敗する

同じイメージでも、実行先のDNS、CAファイル、外向き通信のルール、NATやプロキシ設定は異なります。起動したコンテナの中で接続先を確認し、ネットワーク担当者へ発生時刻と宛先ホスト・ポートを伝えます。名前解決が失敗したなら実行環境のDNSを、接続が拒否されたなら許可済み宛先への443番通信や指定プロキシへの経路を修正します。

許可変更が必要なら、管理者の承認された設定で行います。IPアドレスの固定やDNSの強制上書きで一時的に通しても、接続先の証明書や運用上の許可を確認できるとは限りません。修復後は、本番と同じプロセス・リージョンで確認を繰り返します。

Azureやゲートウェイへ送っている

OpenAI互換のSDKを使っていても、通信先が api.openai.com とは限りません。Azure OpenAIなら対象リソースのエンドポイント、デプロイ、APIバージョンと、そのリソースのネットワーク設定を確認します。他社ゲートウェイなら、その提供元の接続先・キー・障害情報を使います。

OpenAI Statusが正常でも、別の提供元や自分の通信経路が正常とは限りません。OpenAI Statusは、OpenAIへ直接接続している要求の発生時間帯を照合する資料として使います。過去の正常表示を、現在の障害の否定材料にはしません。ブラウザからの呼び出しだけで失敗する場合は、バックエンドの接続診断に加えてブラウザのネットワークエラーやCORSの表示を確認し、秘密のAPIキーをクライアント側へ配布しない設計にします。

再試行とタイムアウトを、処理全体の期限に合わせる

現在のPython・Node SDKは、対象の接続エラーや408、409、429、500以上のエラーを、既定で2回再試行します。Pythonは max_retries、Nodeは maxRetries で変更できます。ただし、再送できるリクエスト本文などの条件があり、すべての例外や処理が同じように再試行されるわけではありません。Python・TypeScriptの説明を、実際のSDK版と照合してください。

診断中は再試行を0にして最初の失敗を見やすくし、復旧後に必要な上限を戻します。アプリの外側でもワーカーやキューが再送するなら、SDKと合わせた最大回数を数えます。CA不足、間違った接続先、拒否されたプロキシは、回数を増やしても修復できません。

タイムアウトの既定値は両SDKとも10分ですが、Pythonの数値は秒、Nodeはミリ秒です。Pythonの timeout=30.0 とNodeの timeout: 30_000 が同じ30秒です。Pythonの現行HTTPX2構成では httpx2.Timeout で接続・読み取り・書き込みなどを分けて指定できます。旧版のHTTPXへ、HTTPX2の名前をそのまま持ち込まないでください。各SDKのタイムアウト説明を見て、外側のHTTPサーバー、関数、ジョブの期限も含めて設定します。

接続の段階で失敗しているなら、長い読み取り時間を増やすより接続設定を直します。接続後の長い生成で読み取りが時間切れになるなら、必要な出力量と処理時間を見直し、アプリ全体の期限に収まる範囲で延長を判断します。外側が先に終了する場合は、SDKの期限だけを延ばしても利用者へ結果を返せません。

ストリーミングの途中で切れた場合

ストリームが返った時点と、最後まで読み終えた時点は違います。例外の捕捉は、要求を開始する箇所だけでなく、受信イベントを読むループまで含めます。途中のテキストは未完了として扱い、完了イベントや正常な読み取り終了を確認してから成功にします。

現行のPython SDKでは、Stream／AsyncStream を読む途中のタイムアウトは APITimeoutError、ほかのHTTP要求の失敗は APIConnectionError として扱われます。受信途中のストリームは自動的に最初から再生されません。 旧来のAssistantsや with_streaming_response の扱いまで同一とは限らないため、使っている方式を公式Pythonリファレンスで確認してください。

途中の出力を保存し、完了状態とエラーを分けて記録します。ツール呼び出しなどで外部への操作を済ませているなら、再要求による重複実行も確認します。最初から再送する場合は、何を再実行してよいかをアプリ側で決め、部分出力を完成した回答として重ねて表示しないようにします。キャンセルしても、サーバー処理や課金が取り消された証明にはなりません。

復旧は「同じ条件で最後まで成功したか」で判断する

設定を直したら、次の順で元の処理へ戻します。

1. 同じプロセス・接続先で、小さい要求の応答を取得する。 同じCA、プロキシ、プロジェクト、利用モデルを使い、意図した結果と取得できたリクエストIDを確認します。curlだけの成功で終了しません。
2. 元の方式で1件を最後まで処理する。 ストリーミングなら完了まで受信し、通常の要求なら本文の解析とアプリへの返却まで確認します。長い入力やファイルを使う処理なら、その条件で別に確認します。
3. 並列数を徐々に戻す。 小さい要求は通るのに負荷を戻すと切れるなら、接続プール、プロキシやNATの容量、クライアントの使い回し、プロセス終了時のクローズ処理を調べます。429へ変わった場合は送信量の問題へ切り分けを進めます。

同じ条件で繰り返し失敗する場合は、原因に合う窓口へ進みます。会社のCA・プロキシで止まるなら社内ネットワーク担当、ゲートウェイで止まるなら提供元、OpenAIからの応答や受領状況を確認したいならOpenAIサポートです。新しいネットワークへ無条件に切り替える前に、失敗が残る場所を伝えます。

問い合わせには、時刻とタイムゾーン、接続先ホストとAPIのパス、SDK・HTTPライブラリのバージョン、実行環境とリージョン、例外と原因の型、経過時間、HTTPステータス、リクエストIDをまとめます。取得できた本文やヘッダーは秘密値を除いた必要部分だけにします。診断ログ全体をそのまま共有せず、プロンプト、認証情報、プロキシの資格情報がないかも確認してください。

よくある質問

request IDがないなら、OpenAIには届いていませんか？

断定できません。送信前に失敗した場合だけでなく、サーバーが受け取った後に応答が失われた場合もあります。OpenAIは、対応するエンドポイントで明示的に送った X-Client-Request-Id を使い、タイムアウトなどで応答IDを取得できない要求の受領状況をサポートが調べられると説明しています。値はASCIIで512文字以内にし、要求を追跡できる一意の値を使います。公式のリクエストID説明を参照してください。

このIDは、自動的な重複排除や課金取消しを保証するキーではありません。APIConnectionError やタイムアウトだけを根拠に未課金と判断せず、受領状況、利用記録、実際の処理結果を照合します。ゲートウェイやAzureでは提供元の追跡方法を確認してください。

APIキーを作り直すと接続エラーは直りますか？

DNS、証明書検証、プロキシや通信許可の失敗なら、キーの作り直しでは直りません。まず同じプロセスの元の例外を確認します。正しいAPIの接続先から401が返ったときは、キーの有効性や権限、組織・プロジェクトを確認する分岐です。

curlは通るのにPythonやNodeだけ失敗するのはなぜですか？

使うCA、プロキシ、HTTPライブラリ、実行ユーザーが違う場合があります。Pythonではインストール済み版がHTTPX2か旧HTTPXか、NodeではSDKが使う fetch とプロキシ設定が対応しているかを確認します。curlのHTTP応答は経路の一部を確かめる材料で、SDKの生成成功を保証しません。