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

> При openai.APIConnectionError: Connection error сначала сохраните исходное исключение и проверьте соединение из неработающего процесса. Отдельно разберите DNS, TLS, прокси и адрес API, а после исправления повторите исходный вызов с ограниченной нагрузкой.

- URL: https://blog.laozhang.ai/ru/posts/openai-api-error-connection-error
- Published: 2026-05-06
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ru/about)
- Topic: Руководства по API
- Tags: OpenAI API, APIConnectionError, Ошибка подключения, Python, Node.js

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

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

Ниже используются [официальные классы ошибок](https://developers.openai.com/api/docs/guides/error-codes) и настройки SDK, сверенные 6 октября 2026 года. Примеры предназначены для вашего приложения; реальные запросы и изменения сетевых настроек при подготовке инструкции не выполнялись.

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

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

| Что удалось получить | Что это позволяет установить | Следующее действие |
| --- | --- | --- |
| `APIConnectionError`, исходная причина связана с DNS, TLS или прокси | Транспорт запроса завершился с ошибкой | Проверить соответствующий этап из неработающего процесса |
| `APITimeoutError` | Истекло время ожидания | Различить ожидание соединения, отправки или чтения; проверить сроки на всех уровнях |
| `APIStatusError` со статусом 401 | Получен HTTP-ответ об аутентификации | Проверить адрес сервера и конфигурацию доступа, не начинать с DNS |
| HTTP 429 и сообщение о частоте запросов | Получено ограничение нагрузки | Разобрать [RPM, TPM и повторы](https://blog.laozhang.ai/ru/posts/openai-api-rate-limit) |
| HTTP 429 и `insufficient_quota` либо сообщение о закончившихся средствах | Получена ошибка квоты или оплаты | Проверить [баланс и месячные лимиты](https://blog.laozhang.ai/ru/posts/openai-api-quota-exceeded-error) |
| HTTP 500 или 503 | Получен ответ об ошибке сервера | Сохранить request ID, проверить состояние сервиса и допустимость ограниченного повтора |

Это разделение соответствует [справочнику Python SDK](https://developers.openai.com/api/reference/python). Если ответ пришёл от корпоративного прокси или стороннего шлюза, его статус сначала нужно сопоставить с документацией этого сервиса. Формат JSON, похожий на OpenAI, не устанавливает отправителя.

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

В Python `APITimeoutError` относится к семейству `APIConnectionError`, поэтому обработчик тайм-аута должен стоять раньше родительского. У `APIConnectionError` исходное исключение доступно через `__cause__`; у `APIStatusError` — статус, ответ и `request_id`. Эти поля позволяют разделить проверки, не выводя ключи или пользовательский запрос в журнал. [Настройки ошибок и времени ожидания](https://developers.openai.com/api/reference/python) описаны в текущей справке SDK.

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

```python
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 из неработающего окружения

![Проверка HTTPS без ключа из той же среды исполнения: отдельно код передачи curl и HTTP-ответ, затем исходный вызов приложения](https://blog.laozhang.ai/posts/ru/openai-api-error-connection-error/img/runtime-https-check.webp)

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

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

```bash
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](https://curl.se/docs/manpage.html).

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

| Результат curl | Что проверять дальше | Условное исправление |
| --- | --- | --- |
| Код 5 или 6 | Разрешение имени прокси или сервера API | Сверить hostname и DNS внутри окружения; исправить ошибку в адресе либо обратиться к администратору DNS |
| Код 7 | TCP-соединение и исходящие правила | Проверить разрешённый выход к нужному серверу на 443, состояние прокси и доступность маршрута |
| Код 35 | TLS-согласование | Уточнить вложенную ошибку, версию TLS и работу промежуточного прокси |
| Код 60 или 77 | Доверие сертификату либо файл CA | Настроить действующее хранилище CA; при корпоративной проверке TLS использовать утверждённый сертификат организации |
| Код 28 | Истекший срок проверки | Выяснить, на каком этапе возникла задержка, и сравнить с исходным исключением SDK |
| Код 52 или 56 | Пустой ответ либо ошибка получения данных | Проверить разрыв соединения, прокси и серверные журналы по времени события |
| Код 97 | Согласование с прокси | Проверить поддерживаемый тип прокси и его транспортные настройки |

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

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

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

![Настройки Python и Node.js, исходная причина соединения, единицы времени и отдельная обработка неизвестной отправки или оборванного потока](https://blog.laozhang.ai/posts/ru/openai-api-error-connection-error/img/sdk-runtime-diagnosis.webp)

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

В Node.js текущая [справка JavaScript/TypeScript SDK](https://developers.openai.com/api/reference/typescript) описывает `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](https://cloud.ru/docs/foundation-models/ug/topics/troubleshooting__openai-error) относится к Foundation Models Cloud.ru: её `API_KEY` и адрес сервера не являются конфигурацией прямого OpenAI. `ping` проверяет другой протокол и не заменяет HTTPS-проверку. Русский язык интерфейса или статьи также не определяет доступность сервиса в конкретном регионе; сетевые исправления должны соблюдать правила поставщика.

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

По текущим справкам [Python](https://developers.openai.com/api/reference/python) и [JavaScript](https://developers.openai.com/api/reference/typescript) 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](https://developers.openai.com/api/reference/overview#supplying-your-own-request-id-with-x-client-request-id).

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

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

Нет. Причиной может быть соединение конкретного процесса, DNS, TLS, прокси или настроенный адрес API. Проверьте [OpenAI Status](https://status.openai.com/) на момент сбоя и сопоставьте сообщение с результатом проверки из приложения. Нормальный статус сервиса не подтверждает доступность вашего маршрута.

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

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

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

Это неизвестно по одному отсутствующему ID. Сбой мог произойти до отправки либо при получении ответа. Для поддерживаемых endpoint заранее добавленный `X-Client-Request-Id` помогает поддержке искать запрос, но не доказывает его исход и оплату. [Правила идентификатора](https://developers.openai.com/api/reference/overview#supplying-your-own-request-id-with-x-client-request-id) относятся к OpenAI, а не автоматически ко всем совместимым шлюзам.

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

Сохраните полный ответ или событие ошибки. Явное сообщение поставщика о средствах требует проверки [квоты и баланса](https://blog.laozhang.ai/ru/posts/openai-api-quota-exceeded-error), даже если интерфейс описал результат как обрыв соединения. Сам обрыв без такого сообщения не устанавливает финансовую причину; название ошибки обёртки тоже не заменяет исходный ответ.

## Источники

Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 2026-10-07.

- [официальные классы ошибок](https://developers.openai.com/api/docs/guides/error-codes) (developers.openai.com)
- [справочнику Python SDK](https://developers.openai.com/api/reference/python) (developers.openai.com)
- [руководстве curl](https://curl.se/docs/manpage.html) (curl.se)
- [справка JavaScript/TypeScript SDK](https://developers.openai.com/api/reference/typescript) (developers.openai.com)
- [документация Cloud.ru](https://cloud.ru/docs/foundation-models/ug/topics/troubleshooting__openai-error) (cloud.ru)
- [API Overview](https://developers.openai.com/api/reference/overview) (developers.openai.com)
- [OpenAI Status](https://status.openai.com/) (status.openai.com)