Отличите таймаут от ошибки соединения
Timeout: запрос ушёл, ответа нет. Connection error: запрос не ушёл. В SDK это разные исключения, в логах разные тексты. От этого зависит, чинить сеть или лимит ожидания.
API timeout и connection error: запрос не дождался ответа или не соединился
Две разные ошибки с похожими симптомами. Таймаут значит, что сервер долго думал; connection error значит, что до сервера вы не дошли вовсе.
/ Короткий ответ
Что это значит
API timeout значит, что соединение установилось, запрос ушёл, но ответ не пришёл за отведённое время, и клиент его бросил. Connection error значит другое: соединение вообще не установилось, до сервера запрос не дошёл. Первое чаще всего про длинную генерацию и слишком короткий лимит ожидания, второе про сеть: прокси, VPN, DNS, закрытый порт или неверный адрес.
У OpenAI SDK лимит ожидания по умолчанию 10 минут, и это относится ко всему запросу целиком. Таймаут ловится как APITimeoutError, ошибка соединения как APIConnectionError. Если вы задали timeout=30 и просите модель написать длинный текст без стриминга, таймаут почти гарантирован: ответ приходит одним куском только после полной генерации. Со стримингом первый токен приходит быстро, а соединение остаётся живым.
Connection error из России часто связан с VPN и прокси: общий IP, обрыв туннеля, DNS, который отдаёт заблокированный адрес. Проверяется одним curl без прокси. Обе ошибки безопасно повторять с растущей паузой, и SDK умеет это через max_retries.
/ Почему
Откуда берётся ошибка
- Короткий timeout при длинной генерации: лимит в клиенте 30–60 секунд, а модель пишет ответ на несколько тысяч токенов.
- Нет стриминга: без stream=true ответ приходит одним куском в конце, и все промежуточные узлы ждут его целиком.
- Прокси или VPN: туннель оборвался, прокси не отвечает, переменные HTTP_PROXY указывают на мёртвый адрес.
- DNS: имя сервера не резолвится или резолвится в адрес, который из вашей сети недоступен.
- Неверный base URL: порт, протокол или домен с опечаткой дают connection error, а не 404.
- Сбой на стороне сервера: перегруженный узел отвечает медленно, и таймаут срабатывает у вас раньше, чем 504 у него.
/ Тексты ошибок
Что пишет клиент и что это значит
| Текст ошибки | Причина | Что делать |
|---|---|---|
| APITimeoutError / Request timed out | Ответ не пришёл за лимит клиента | Поднять timeout, включить стриминг, укоротить запрос |
| APIConnectionError / Connection error | Соединение не установилось | Проверить прокси, VPN, DNS и адрес одним curl |
| getaddrinfo ENOTFOUND / Name or service not known | DNS не нашёл имя сервера | Проверить base URL и DNS-сервер сети |
| ECONNRESET / Connection reset by peer | Соединение оборвано по дороге | Отключить туннель и повторить; проверить прокси |
| ETIMEDOUT на этапе connect | Порт или адрес недоступен из сети | Проверить порт 443 и правила файрвола |
Тексты приведены по исключениям OpenAI SDK и типичным ошибкам Node.js и Python; в других библиотеках формулировки отличаются.
/ Что делать
Порядок действий
Проверьте адрес одним curl без прокси
Если команда отвечает за секунды, сеть в порядке и дело в лимите. Если висит или падает, проблема между вами и сервером.
curl -sS -m 20 -o /dev/null -w "%{http_code} %{time_total}s\n" \
https://api.kosareva.cloud/v1/models -H "Authorization: Bearer $KEY"Задайте timeout и max_retries явно
Лимит ожидания подбирайте под задачу: для чата 60 секунд, для длинных документов несколько минут. Повторы SDK сделает сам с растущей паузой.
from openai import OpenAI
client = OpenAI(
base_url="https://api.kosareva.cloud/v1",
api_key="KEY",
timeout=180, # секунды на весь запрос
max_retries=3, # повторы при таймауте и сетевых ошибках
)Включите стриминг для длинных ответов
stream=True в SDK или "stream": true в теле запроса. Первые токены приходят через секунды, и ни клиент, ни промежуточные узлы не обрывают соединение по таймауту.
Уберите лишние звенья из сети
Проверьте переменные HTTP_PROXY и HTTPS_PROXY, отключите VPN, если адрес доступен напрямую, замените DNS на публичный. Каждое звено добавляет задержку и свою точку отказа.
/ По инструментам
Где это чинится в разных инструментах
- Python и Node.js SDK. Исключения APITimeoutError и APIConnectionError. Оба покрываются max_retries; timeout задаётся в клиенте или на уровне одного запроса через with_options.
- Cursor, Cline, Continue. Таймаут в настройках провайдера или в конфиге; для агентных задач с длинным выводом ставьте не меньше 2–3 минут.
- n8n и Make. У HTTP-ноды свой лимит ожидания, по умолчанию небольшой. Поднимите его в настройках ноды и включите Retry On Fail.
- LangChain. Параметры request_timeout и max_retries у модели; стриминг через .stream() вместо .invoke().
- Claude Code и Codex CLI. Connection error здесь почти всегда про сеть или неверный base URL: проверьте переменные окружения и прокси в той же оболочке, где запускаете инструмент.
/ FAQ
Частые вопросы
Какой timeout ставить?
Под задачу: 60 секунд для короткого чата, 3–5 минут для длинных документов без стриминга. По умолчанию у OpenAI SDK 10 минут, и это слишком много для интерактивных сценариев.
Спишут ли токены за запрос, который отвалился по таймауту?
Сервер мог успеть выполнить запрос и сгенерировать ответ, который вы не получили. Поэтому для длинных задач включайте стриминг: полученная часть не теряется.
Почему connection error появляется только с VPN?
Туннель добавляет своё звено: общий IP, свой DNS, обрывы при переподключении. Если адрес доступен напрямую, VPN для него не нужен.
/ На kosareva.cloud
Как это выглядит у нас
Наш адрес https://api.kosareva.cloud/v1 доступен с российских IP без VPN и прокси, поэтому лишних звеньев в сети не нужно: connection error из-за туннеля отпадает. Стриминг поддерживается в OpenAI- и Anthropic-формате, таймауты и повторы задаются в вашем SDK как обычно. Если запрос всё же отвалился, расход по ключу виден в кабинете, и легко проверить, что было выполнено.
/ Дальше
Рядом в справочнике
Ключ, который работает из России
OpenAI-совместимый адрес, оплата в рублях, ключ сразу после регистрации. Пополнение картой от 50 ₽.