openai.APIConnectionError: Connection error означает, что SDK не завершил путь подключения к настроенному endpoint. Если нет HTTP-статуса, тела ответа и request ID, сначала проверяйте маршрут между вашим runtime и OpenAI. Не меняйте ключи, биллинг, модель или prompt до того, как понятно, дошел ли запрос до сервера.
Если статус уже вернулся, владелец меняется. 401 относится к аутентификации, 429 к quota или rate limit, 500 и 503 к серверной или временной ветке. Эта страница про ветку без ответа. На момент проверки 6 мая 2026 года страница OpenAI Status была зеленой; официальная документация OpenAI описывает APIConnectionError как проблему подключения к сервисам и предлагает проверить сеть, proxy, SSL certificates, firewall rules и container permissions.
Быстрая развилка
| Доказательство | Кого проверять первым | Действие |
|---|---|---|
| Нет status, body, request ID | Маршрут подключения | Проверьте status, DNS, TLS, proxy, firewall и egress из того же runtime. |
| Вернулся 401 | Auth ветка | Проверьте key, project, organization и тип endpoint. |
| Вернулся 429 или rate headers | Quota/rate ветка | Перейдите к лимитам или quota, а не к сетевой диагностике. |
| Вернулся 500/503 и request ID | API/server ветка | Сохраните request ID, retry ограниченно, проверьте status. |
| Azure или gateway | Provider route | Проверьте base URL, deployment, статус провайдера и outbound HTTPS. |
Сначала смотрите на evidence ответа
APIConnectionError полезен именно тем, что часто не дает статус-кода для классификации. В текущих README SDK connection failures отделены от APIStatusError, который появляется после 4xx или 5xx ответа. Поэтому отсутствие статуса уже является фактом.
Сначала смотрите underlying cause: remote disconnect, DNS failure, TLS error, proxy error, timeout или connection refused. Если видите 429, insufficient_quota или rate headers, это соседняя ветка OpenAI API rate limits или quota, а не connection path. Нельзя смешивать эти случаи в один совет про retry.
Слепой retry может сделать шум меньше, но скрыть владельца. Новый key добавляет переменную. Переход на другой gateway доказывает только то, что другой маршрут может работать. В production сначала докажите исходный маршрут.
10-минутный тест того же маршрута
Проверки должны идти с той же машины, контейнера, serverless function, worker, региона и base URL, где упал запрос. Успех на ноутбуке не доказывает здоровье production route.
- Откройте https://status.openai.com/ и запишите время.
- Проверьте DNS для реального hostname: api.openai.com, Azure resource или gateway host.
- Проверьте outbound TLS на 443 из того же runtime.
- Сверьте base URL и endpoint family.
- Найдите proxy, VPN, firewall, WAF или NAT, которые могут менять маршрут.
- Сравнивайте local и deployed только при одинаковых key, model, endpoint и env vars.
Фиксируйте не только pass/fail. DNS, TLS, proxy refusal, remote disconnect и timeout ведут к разным исправлениям.
SDK-контроли должны сохранять evidence
В Python ловите APIConnectionError отдельно от APITimeoutError и APIStatusError. Во время диагностики задайте понятный timeout, уменьшите max_retries и включите debug logging только для сбора cause. В Node используйте maxRetries, timeout, request IDs, raw response и proxy fetch как инструменты доказательства, а не как способ спрятать owner.
Бесконечные retry недопустимы. Они не исправят bad CA bundle, закрытый egress, неверный base URL или заблокированный proxy. Держите один минимальный same-route request как probe. Когда он проходит, возвращайте реальную нагрузку.
Ветки маршрута
Для direct OpenAI сначала докажите путь к api.openai.com, затем разбирайте возвращенные статусы. Для Azure OpenAI проверьте resource endpoint, deployment name, API version, region routing и network rules. OpenAI-compatible gateway считается provider route, пока direct OpenAI test не покажет тот же симптом.
Browser-side вызовы имеют отдельные владельцы: CORS, leaked keys, browser networking и proxy design. Для production переносите вызов server-side.
Serverless и контейнеры требуют проверки изнутри работающего runtime. Успешный build или package install не доказывает runtime egress.
Пакет для эскалации
Перед support или provider escalation соберите timestamp и timezone, endpoint/base URL, SDK и version, model, runtime и region, direct OpenAI или Azure/gateway route, underlying exception, наличие status/body/request ID и очищенные логи. Не добавляйте API keys, secret headers или customer data.
Хорошая строка evidence звучит так: status page проверен 2026-05-06 22:40 CST; DNS в контейнере работает; TLS падает на corporate CA; request ID нет. Это лучше, чем скриншот без маршрута.
Если команда использует несколько окружений, добавьте к пакету матрицу отличий: local dev, staging worker, production worker, region, proxy profile и base URL. APIConnectionError часто появляется только в одном из этих мест, потому что outbound policy, DNS resolver или CA bundle отличаются. Такая матрица сразу показывает, что менять нужно в сети или runtime, а не в prompt и не в лимитах.
FAQ
APIConnectionError значит, что OpenAI не работает?
Нет. Это значит, что ваш запрос не завершил путь подключения. Проблема может быть в DNS, TLS, proxy, firewall, container egress, endpoint или gateway route.
Почему нет request ID?
Обычно запрос не дошел до точки, где API мог вернуть ответ. Возвращенная API ошибка чаще имеет request evidence; connection failure часто нет.
Нужно ли менять API key?
Не сначала. Key rotation относится к auth owner. Если вернулся 401, проверяйте auth. Если ответа нет, проверяйте маршрут.
Это rate limit?
Обычно нет. Rate limit возвращает 429 или headers. Тогда используйте OpenAI API rate limits.