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 또는 temporary availability 분기입니다. no-response branch에서는 API 증거가 돌아오기 전에 요청이 실패한 상태를 먼저 봅니다. 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 | 연결 오류가 아니라 quota 또는 rate limit 분기. |
| 500/503과 request ID | API/server | request ID 보존, 제한적 retry, status 확인. |
| Azure 또는 gateway | provider route | base URL, deployment, provider status, outbound HTTPS 확인. |
응답 증거를 먼저 읽기
APIConnectionError는 SDK가 분류할 server response를 갖지 못한 상태를 보여주는 경우가 많습니다. 현재 SDK 문서에서는 connection failures와 returned 4xx/5xx가 다른 예외 계층으로 나뉩니다. 그러므로 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 조언으로 합치면 owner가 사라집니다.
10분 동일 경로 테스트
실패한 같은 machine, container, serverless function, worker, region, base URL에서 검사합니다. 로컬 성공은 production route의 증거가 아닙니다.
- https://status.openai.com/을 열고 시간을 기록합니다.
- 실제 hostname의 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는 underlying 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-side 호출은 CORS, leaked key, browser networking, proxy design이 owner가 될 수 있습니다. production API 호출은 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는 포함하지 마세요.
예를 들어 status page checked at 2026-05-06 22:40 CST, DNS resolved inside container, TLS failed with corporate CA, no request ID returned라고 쓰면 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로 이동하세요.