Ошибка подключения OpenAI API: сначала проверьте маршрут APIConnectionError

openai.APIConnectionError: Connection error. означает, что Python SDK не смог завершить HTTP-запрос из-за сбоя соединения. Сначала получите исходное исключение через __cause__ и проверьте настроенный адрес API в том процессе, где возникает ошибка. Если приложение работает в контейнере, проверка с вашего ноутбука не заменяет проверку внутри контейнера. Если сервер уже вернул 401, 429 или 503, разбирайте этот ответ: для него предусмотрены другие классы ошибок.

Практический порядок такой: отключить дополнительные повторы на время диагностики, записать причину первого сбоя, проверить HTTPS без ключа к нужному серверу, исправить найденное различие в настройках и подтвердить работу исходного вызова. Отсутствие HTTP-статуса или request ID само по себе не доказывает, что сервер не получил запрос: ответ мог потеряться после отправки.

Ниже используются официальные классы ошибок и настройки SDK, сверенные 6 октября 2026 года. Примеры предназначены для вашего приложения; реальные запросы и изменения сетевых настроек при подготовке инструкции не выполнялись.

Сначала отличите сбой соединения от ответа API

Не ограничивайтесь строкой «ошибка подключения» в интерфейсе. Сохраните класс исключения, исходную причину, доступный статус и идентификатор запроса. Обёртка приложения или интеграции может скрыть более полезное сообщение.

Это разделение соответствует справочнику Python SDK. Если ответ пришёл от корпоративного прокси или стороннего шлюза, его статус сначала нужно сопоставить с документацией этого сервиса. Формат JSON, похожий на OpenAI, не устанавливает отправителя.

Получите причину в том же Python-процессе

В Python APITimeoutError относится к семейству APIConnectionError, поэтому обработчик тайм-аута должен стоять раньше родительского. У APIConnectionError исходное исключение доступно через __cause__; у APIStatusError — статус, ответ и request_id. Эти поля позволяют разделить проверки, не выводя ключи или пользовательский запрос в журнал. Настройки ошибок и времени ожидания описаны в текущей справке SDK.

Следующий фрагмент встраивается в синхронное приложение. client — уже настроенный клиент этого приложения, а send — функция, которая принимает клиент и выполняет ваш существующий вызов API. Нужны установленный пакет openai и тот же набор настроек подключения. Здесь нет заранее выбранной модели или нового endpoint:

import openai


def diagnose_sync(client, send):
    diagnostic_client = client.with_options(
        max_retries=0,
        timeout=20.0,
    )
    try:
        return send(diagnostic_client)
    except openai.APITimeoutError as exc:
        print({
            "kind": "timeout",
            "cause_type": type(exc.__cause__).__name__,
        })
        raise
    except openai.APIConnectionError as exc:
        print({
            "kind": "connection",
            "cause_type": type(exc.__cause__).__name__,
        })
        raise
    except openai.APIStatusError as exc:
        print({
            "kind": "http_response",
            "status": exc.status_code,
            "request_id": exc.request_id,
        })
        raise

Значение 20.0 — пример 20-секундного ожидания для диагностики, а не рекомендуемый срок любой генерации. max_retries=0 отключает дополнительные отправки внутри SDK: иначе один вызов может скрывать несколько попыток. Функция повторно поднимает исключение, чтобы приложение не приняло диагностическую запись за успешный результат. Полный текст исходной причины при необходимости изучайте в закрытом журнале после удаления секретов: даже адрес прокси иногда содержит данные авторизации.

Если ошибка появляется в AsyncOpenAI, поставьте такие же обработчики вокруг существующего await-вызова. Синхронную функцию выше нельзя просто использовать вместо асинхронного вызова. Если сбой происходит при чтении stream, обработчик нужен и вокруг цикла чтения, а не только вокруг создания потока.

Проверьте также версию установленного SDK и HTTP-библиотеки. Текущая справка Python описывает HTTPX2, включая httpx2.Timeout и DefaultHttpx2Client; старые версии SDK могут использовать HTTPX и другие имена клиентов. Настройку доверенного CA или прокси выбирайте по документации своей версии. Простое числовое timeout в Python задаётся в секундах; оно не требует переносить имена транспортных фабрик из другой версии. Не исправляйте библиотеку через её приватные классы: сначала установите, какой транспорт действительно использует приложение.

Проверьте HTTPS из неработающего окружения

Перед проверкой уточните фактические base_url, hostname и endpoint. Для прямого OpenAI API адрес сервера — https://api.openai.com/v1; для Azure или совместимого провайдера он другой. Если используете прокси, его адрес относится к транспортным настройкам, а не подставляется вместо адреса API.

Выполните следующую команду в shell нужного контейнера или сервера. Она обращается к прямому OpenAI без заголовка авторизации и без генерации. Для другого поставщика используйте известный HTTPS-адрес из его документации; не отправляйте ключ на адрес, выбранный наугад.

curl -q --connect-timeout 5 --max-time 15 \
  --output /dev/null \
  --write-out 'HTTP=%{http_code}\n' \
  https://api.openai.com/v1/models
curl_exit=$?
printf 'curl_exit=%s\n' "$curl_exit"

-q первым аргументом запрещает чтение стандартного curlrc. Он не отключает настройки прокси из окружения и не ослабляет проверку TLS. --connect-timeout ограничивает этап подключения, включая DNS и TLS, а --max-time — всю проверку; оба значения здесь в секундах. Назначение параметров и кодов завершения описано в руководстве curl.

Смотрите на две строки результата. Без --fail curl может завершиться с кодом 0, получив HTTP 401, 429 или 503. Поэтому curl_exit=0 означает успешное выполнение передачи, а не успешный вызов модели. HTTP-ответ без ключа проверяет доступность HTTPS по этому маршруту; он не проверяет права ключа, баланс и генерацию.

Коды указывают направление проверки, а не единственную доказанную причину. HTTP=000 означает, что эта проверка не получила HTTP-статус; это не доказательство отсутствия обработки другого запроса.

Если curl тоже падает, исправляйте найденный сетевой этап. Если curl получает ответ, а SDK по-прежнему не работает, сравните DNS, прокси, доверенные сертификаты и ограничения конкретного процесса. Даже на одном сервере shell и приложение могут использовать разные CA, переменные окружения и HTTP-транспорты. Не отключайте проверку сертификатов ради успешной строки: после такого изменения результат уже не подтверждает нормальное защищённое соединение.

Прокси, Node.js и контейнер: где настройки расходятся

Успешное соединение браузера не означает, что Python или Node.js наследует его настройки. Сначала проверьте, настроен ли разрешённый прокси в HTTP-клиенте приложения и совпадает ли его протокол с выбранным транспортом. Если прокси требует авторизацию, проверяйте её источник, не публикуя URL с логином и паролем.

В Node.js текущая справка JavaScript/TypeScript SDK описывает fetch и fetchOptions. Для прокси с undici нужно передать соответствующий fetch из undici и ProxyAgent через fetchOptions.dispatcher вместе. Добавленный dispatcher не становится рабочим параметром произвольного fetch. Старый пример с httpAgent также нельзя считать универсальным для текущего клиента. У Bun настройка прокси и у Deno createHttpClient устроены иначе; используйте раздел своей среды исполнения.

Параметры Node-клиента maxRetries: 0 и timeout: 20_000 задают отсутствие дополнительных повторов и 20 секунд ожидания. В отличие от Python, здесь единица времени — миллисекунда. По текущей справке ошибка истечения срока называется APIConnectionTimeoutError. Если приложение использует AbortSignal, проверьте, кто и когда отменяет запрос: отмена со стороны приложения не равна недоступности сервера.

В контейнере или serverless-среде сопоставьте конфигурацию работающего процесса с локальной:

• Настроенный адрес API и выбранный endpoint действительно совпадают, а переменная конфигурации не подменяет base_url.
• Нужные переменные переданы в работающий экземпляр, а не только в сборку образа. Секреты сверяйте через их безопасные идентификаторы, не через вывод значений.
• Разрешён исходящий HTTPS, доступен настроенный прокси и присутствует доверенное хранилище CA.
• Асинхронный клиент не используется после закрытия и закрывается до завершения event loop. Клиент переиспользуется в пределах подходящего жизненного цикла приложения.

Если сбой наблюдается только под нагрузкой, сравните число одновременных запросов, доступные соединения пула и время их ожидания. Сначала ограничьте нагрузку и проверьте результат; увеличение всех тайм-аутов не исправляет исчерпание ресурсов.

Для Azure проверяйте адрес своего ресурса, deployment и сетевые правила этого ресурса. Для Cloud.ru и других OpenAI-совместимых API — их собственные endpoint и настройки доступа. Например, документация Cloud.ru относится к Foundation Models Cloud.ru: её API_KEY и адрес сервера не являются конфигурацией прямого OpenAI. ping проверяет другой протокол и не заменяет HTTPS-проверку. Русский язык интерфейса или статьи также не определяет доступность сервиса в конкретном регионе; сетевые исправления должны соблюдать правила поставщика.

Тайм-ауты и повторы: когда можно пробовать снова

По текущим справкам Python и JavaScript SDK по умолчанию допускают два дополнительных повтора подходящих ошибок, а стандартное время ожидания составляет 10 минут. В Python оно задаётся в секундах, в JavaScript — в миллисекундах. Однако reverse proxy, сервер приложения или платформа могут прекратить ожидание раньше клиента.

Согласуйте срок выполнения задания с временем ожидания HTTP и числом попыток. Во время диагностики оставьте одну отправку. После устранения причины верните ограниченные повторы для временных сбоев, учитывая повторы самого рабочего процесса: несколько уровней могут неожиданно умножить число отправок. Неверный адрес, недоверенный CA и закрытый сетевой выход требуют исправления конфигурации, а не увеличения паузы.

Если ответ начал поступать потоком, не запускайте тот же запрос заново автоматически. Текущая справка Python SDK отдельно указывает, что ошибки при чтении stream не приводят к его автоматическому воспроизведению. Уже полученный текст нужно сохранить и явно решить, нужен ли новый запрос. Если модель вызывает инструменты с побочными действиями, приложение также должно предотвратить повторное выполнение этих действий.

При тайм-ауте до получения ответа исход операции может оставаться неизвестным: запрос мог попасть на сервер, а ответ — не вернуться. Отмена через AbortSignal не доказывает откат обработки. Без отдельного подтверждения нельзя обещать, что неудачный вызов не оплачивается или что повтор не создаст дополнительную работу.

Подтвердите восстановление исходного вызова

После исправления сначала повторите HTTPS-проверку, затем выполните один небольшой вызов в том же приложении, с теми же адресом API, ключом, проектом, endpoint и моделью. Для проверки генерации используйте минимальный допустимый вход и разумный предел ответа. Такой вызов является реальным использованием API и выполняется по обычным условиям оплаты.

Признак восстановления — ожидаемый ответ исходной операции, а для потокового запроса ещё и нормальное завершение чтения. Работающий список моделей, успешная установка пакета или новый клиент сами по себе этого не подтверждают. Если появился HTTP-статус ошибки, соединение уже проверяется иначе: вернитесь к таблице ответов и разберите новый статус.

Если небольшой вызов проходит, постепенно верните типичную нагрузку и наблюдайте за задержкой и ошибками. Один успешный ответ подтверждает конкретный вызов, но не устойчивость всей очереди. Если работает только другой сервер или другой провайдер, запишите это как различие маршрутов: исходное соединение ещё не восстановлено.

Если причина остаётся неясной, передайте поддержке время с часовым поясом, безопасно записанный адрес API, среду исполнения и регион, версии SDK и HTTP-клиента, класс ошибки и очищенную исходную причину, стадию сбоя, число попыток и доступный x-request-id. Укажите, начался ли ответ и какая часть потока была получена. Не прикладывайте ключи, заголовки авторизации и содержимое запросов клиентов.

При отсутствии серверного идентификатора можно заранее задать уникальный X-Client-Request-Id: для поддерживаемых endpoint OpenAI разрешает ASCII-строку длиной до 512 символов и описывает её использование при поиске запроса поддержкой. Это поле нужно добавлять явно; оно не является ключом идемпотентности и не гарантирует отсутствие повторной обработки. Условия приведены в API Overview.

Частые вопросы

APIConnectionError означает, что OpenAI сейчас недоступен?

Нет. Причиной может быть соединение конкретного процесса, DNS, TLS, прокси или настроенный адрес API. Проверьте OpenAI Status на момент сбоя и сопоставьте сообщение с результатом проверки из приложения. Нормальный статус сервиса не подтверждает доступность вашего маршрута.

Нужно ли менять API-ключ при Connection error?

Начните с исходной сетевой причины и адреса сервера. Смена ключа не исправит DNS или доверие сертификату. Если получен 401, проверьте конфигурацию доступа; если ключ раскрыт, его замена нужна независимо от сетевой ошибки. Не выводите ключ в терминал ради проверки его наличия.

Почему нет request ID: запрос не дошёл до OpenAI?

Это неизвестно по одному отсутствующему ID. Сбой мог произойти до отправки либо при получении ответа. Для поддерживаемых endpoint заранее добавленный X-Client-Request-Id помогает поддержке искать запрос, но не доказывает его исход и оплату. Правила идентификатора относятся к OpenAI, а не автоматически ко всем совместимым шлюзам.

Поток оборвался с сообщением о закончившихся кредитах — это сетевая ошибка?

Сохраните полный ответ или событие ошибки. Явное сообщение поставщика о средствах требует проверки квоты и баланса, даже если интерфейс описал результат как обрыв соединения. Сам обрыв без такого сообщения не устанавливает финансовую причину; название ошибки обёртки тоже не заменяет исходный ответ.