openai.APIConnectionError: Connection error は、SDK が設定済み endpoint までの接続経路を完了できなかったという意味です。HTTP status、JSON body、request ID がないなら、API key、billing、model、prompt を変える前に、runtime から OpenAI までの経路を調べます。
status が返っている場合は owner が変わります。401 は認証、429 は quota または rate limit、500/503 は server 側または一時的な可用性の分岐です。no-response branch では、API 証拠が戻る前に request が失敗しています。2026 年 5 月 6 日の確認時点で OpenAI Status は正常でした。OpenAI の公式エラーコード文書は APIConnectionError を services への接続問題として説明し、network settings、proxy、SSL certificates、firewall rules、container permissions の確認を求めています。
最初の切り分け
| ある証拠 | 最初に見る owner | 次の動き |
|---|---|---|
| status、body、request ID がない | 接続経路 | 同じ runtime から status、DNS、TLS、proxy、firewall、egress を確認。 |
| 401 が返る | 認証 | key、project、organization、endpoint family を確認。 |
| 429 または rate headers | quota/rate | 接続ではなく rate limit または quota 分岐へ。 |
| 500/503 と request ID | API/server | request ID を残し、限定的に retry。 |
| Azure/gateway | provider route | base URL、deployment、provider status、outbound HTTPS を確認。 |
まずレスポンス証拠を見る
APIConnectionError は、SDK が分類できる server response を持っていないことが多い点が重要です。現在の SDK README では、connection failures は APIConnectionError、返ってきた 4xx/5xx は APIStatusError として扱われます。つまり status がないこと自体が evidence です。
remote disconnect、DNS failure、TLS certificate error、proxy error、timeout が見えるなら connection path を追います。429、insufficient_quota、rate headers があるなら OpenAI API rate limits や quota branch です。ひとつの retry advice にまとめると owner を失います。
10分の同一経路テスト
失敗した同じ machine、container、serverless function、worker、region、base URL から確認します。ローカルで通ることは、本番 route が通る証明ではありません。
- https://status.openai.com/ を開き、時刻を記録する。
- 実際の host の DNS を確認する。
- 同じ runtime から 443 の TLS を確認する。
- direct OpenAI、Azure OpenAI、gateway の base URL を混ぜていないか見る。
- proxy、VPN、firewall、WAF、NAT が通信を止めていないか見る。
- key、model、endpoint、env vars が一致してから local と deployed を比較する。
pass/fail だけでは不十分です。最初に変化した証拠が DNS、TLS、proxy refusal、remote disconnect、timeout のどれかで修正が変わります。
SDK 制御で証拠を隠さない
Python では APIConnectionError、APITimeoutError、APIStatusError を分けて捕捉します。診断中は timeout を明示し、max_retries を下げ、OPENAI_LOG=debug は cause を取る範囲で使います。Node では maxRetries、timeout、request ID、raw response、proxy fetch を同じ目的で使います。
無限 retry は避けます。blocked proxy、bad CA bundle、wrong base URL、closed container egress は retry では直りません。最小の same-route request を probe として持ち、それが通ってから本来の workload に戻します。
Route branch で修正が変わる
Direct OpenAI は api.openai.com への経路を先に確認します。Azure OpenAI は resource endpoint、deployment name、API version、region routing、network rules を追加で見ます。OpenAI-compatible gateway は、direct OpenAI でも同じ症状が出るまで provider route として扱います。
Browser から直接呼ぶ場合は CORS、leaked key、browser networking、proxy design が owner になり得ます。production では server-side に寄せてから SDK path を診断します。
エスカレーション用証拠
support や provider に渡す前に、timestamp と timezone、endpoint/base URL、SDK と version、model、runtime と region、direct OpenAI か Azure/gateway か、underlying exception、status/body/request ID の有無、sanitized logs をまとめます。API key や secret header は入れません。
「2026-05-06 22:40 CST に status page は正常、container 内 DNS は成功、TLS が corporate CA で失敗、request ID はなし」のように書けると、単なる screenshot より有用です。
FAQ
APIConnectionError は OpenAI 障害ですか？
いいえ。接続経路が完了しなかったという意味です。DNS、TLS、proxy、firewall、container egress、endpoint、gateway route が owner かもしれません。
request ID がないのはなぜですか？
API が response を返せる地点まで届いていないことが多いからです。
API key を替えるべきですか？
最初ではありません。401 が返ったら auth を見ます。response がなければ route を見ます。
rate limit と同じですか？
通常は違います。429 や rate headers があるなら OpenAI API rate limits を使います。