Коды ошибок curl: полный справочник

Краткая справочная таблица

Ошибка 6: не удалось разрешить имя хоста

Что это значит

В терминале вы видите curl: (6) Could not resolve host. curl не смог преобразовать доменное имя в IP-адрес — DNS-запрос завершился неудачно ещё до попытки установить соединение.

Причины

Наиболее частые причины: опечатка в имени хоста (например, curl https://apiexample.com вместо api.example.com), проблемы с DNS-сервером (настроенный DNS недоступен или не работает), отсутствие сетевого подключения (Wi-Fi отключён, VPN не подключён) или домен действительно не существует.

Как исправить

Сначала проверьте правильность URL. Затем протестируйте DNS-разрешение напрямую: nslookup api.example.com или dig api.example.com. Если DNS не работает, попробуйте другой DNS-сервер: curl --dns-servers 8.8.8.8 https://api.example.com. Проверьте /etc/resolv.conf или сетевые настройки. Если вы за корпоративным VPN, убедитесь, что внутренний DNS может разрешить данный хост.

$ curl https://api.exmple.com/users

Ошибка 7: не удалось подключиться

Что это значит

В терминале вы видите curl: (7) Failed to connect to host port: Connection refused. curl разрешил имя хоста, но не смог установить TCP-соединение с сервером — соединение было отклонено или истекло время ожидания на уровне TCP.

Причины

Частые причины: сервер не запущен или не работает, файрвол блокирует порт (проверьте как локальный, так и серверный файрвол), неправильный порт (например, сервис работает на 8080, а вы подключаетесь к 443) или очередь подключений сервера переполнена при высокой нагрузке.

Как исправить

Проверьте, что сервер работает: ping api.example.com и telnet api.example.com 443. Убедитесь, что нужный порт открыт: nmap -p 443 api.example.com. Временно отключите локальный файрвол для теста. Если используете Docker, проверьте, что порт контейнера опубликован. Попробуйте с verbose-режимом: curl -v https://api.example.com, чтобы увидеть, где именно соединение обрывается.

$ curl https://localhost:8080/api

Ошибка 22: HTTP вернул ошибку

Что это значит

В терминале вы видите curl: (22) The requested URL returned error. Сервер вернул HTTP-код ошибки (4xx или 5xx), а curl был запущен с флагом -f или --fail, который указывает curl считать HTTP-ошибки неудачами.

Причины

Ошибка срабатывает при HTTP-кодах состояния: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) или 500 (Internal Server Error) — но только при использовании --fail. Без --fail curl возвращает код 0 даже при HTTP-ошибках. Частые причины: неправильный URL, отсутствие аутентификации, недостаточные права доступа или ошибка на стороне сервера.

Как исправить

Запустите curl без --fail, чтобы увидеть полное тело ответа — оно часто содержит описание реальной ошибки. Проверьте HTTP-код: curl -w "%{http_code}" -o /dev/null -s URL. Для 401/403: проверьте токен авторизации или API-ключ. Для 404: перепроверьте путь URL. Для 500: проблема на стороне сервера.

$ curl --fail https://api.example.com/nonexistent

Ошибка 28: истекло время ожидания операции

Что это значит

В терминале вы видите curl: (28) Operation timed out или curl: (28) Connection timed out. Операция заняла больше допустимого времени. Это самая распространённая ошибка curl — она может возникнуть на этапе DNS-разрешения, TCP-подключения, SSL-рукопожатия или передачи данных.

Причины

Типичные причины: медленный или перегруженный сервер не отвечает вовремя, загруженность сети или потеря пакетов, файрвол молча отбрасывает пакеты (без отказа, просто тишина), слишком строгие таймауты, заданные через --connect-timeout или --max-time, или неправильная настройка прокси, вызывающая задержки.

Как исправить

Увеличьте таймаут: curl --connect-timeout 30 --max-time 120 URL. Используйте verbose-режим, чтобы увидеть, где curl зависает: curl -v URL. Проверьте задержку сети: ping api.example.com и traceroute api.example.com. Если вы за прокси, попробуйте обойти его: curl --noproxy '*' URL. Для передачи больших файлов используйте --retry 3 с --retry-delay 5 для автоматических повторов.

$ curl --connect-timeout 5 https://slow-api.example.com/data

Ошибка 35: ошибка SSL-подключения

Что это значит

В терминале вы видите curl: (35) SSL connect error. SSL/TLS-рукопожатие не удалось — curl не смог установить защищённое соединение с сервером.

Причины

Частые причины: несовместимость версий TLS (сервер требует TLS 1.3, а ваш curl поддерживает только TLS 1.2), несовместимость наборов шифров, неправильная SSL-конфигурация сервера (просроченный сертификат при рукопожатии, неполная цепочка), сервер не поддерживает HTTPS на указанном порту, или прокси или файрвол перехватывает SSL-соединение (MITM).

Как исправить

Принудительно укажите версию TLS: curl --tlsv1.2 URL или curl --tlsv1.3 URL. Проверьте, что поддерживает сервер: openssl s_client -connect api.example.com:443. Обновите curl и OpenSSL до последних версий. Если сервер использует самоподписанный сертификат, обычно возникает ошибка 60 — ошибка 35 указывает на сбой рукопожатия на уровне протокола.

$ curl https://legacy-server.example.com/api

Ошибка 56: сбой приёма данных — соединение сброшено

Что это значит

В терминале вы видите curl: (56) Recv failure: Connection reset by peer. Соединение было установлено успешно, но приём данных не удался — сервер закрыл или сбросил соединение неожиданно во время передачи.

Причины

Это часто происходит, когда: сервер падает или перезапускается во время передачи, балансировщик нагрузки или прокси разрывает соединение (таймаут простоя, слишком большой запрос), файрвол завершает долгоживущие соединения, у сервера таймаут keep-alive меньше ожидаемого, или происходит сбой сети между клиентом и сервером.

Как исправить

Повторите запрос — временные сетевые проблемы являются самой частой причиной. Используйте verbose-режим: curl -v URL, чтобы увидеть точный момент сбоя. Если ошибка возникает при больших загрузках, попробуйте chunked-передачу: curl -H "Transfer-Encoding: chunked" URL. Для операций Git с ошибкой RPC failed; curl 56 увеличьте буфер: git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

Ошибка 60: проблема с SSL-сертификатом

Что это значит

В терминале вы видите curl: (60) SSL certificate problem: unable to get local issuer certificate. curl не смог проверить SSL-сертификат сервера по хранилищу CA (Certificate Authority). TLS-рукопожатие завершилось на уровне протокола, но проверка сертификата не прошла.

Причины

Наиболее частые причины: сервер использует самоподписанный сертификат, сертификат просрочен, цепочка сертификатов неполная (отсутствуют промежуточные сертификаты), хранилище CA устарело (часто на старых системах или в Docker-контейнерах), или Common Name / SAN сертификата не совпадает с запрашиваемым именем хоста.

Как исправить

Обновите хранилище CA: curl --cacert /path/to/cacert.pem URL. Скачайте актуальное хранилище с https://curl.se/ca/cacert.pem. Для диагностики: openssl s_client -connect api.example.com:443 -showcerts. Для самоподписанных сертификатов в разработке используйте curl -k URL (никогда в продакшене — это отключает всю проверку сертификатов). В Docker установите пакет ca-certificates.

$ curl https://self-signed.example.com/api

Другие коды ошибок

Как отлаживать ошибки curl

Когда curl завершается с ошибкой, эти три флага помогут быстро определить причину — от DNS-разрешения до SSL-рукопожатия и тела ответа.

1. 1

   Включите подробный вывод

   Запустите curl -v URL, чтобы увидеть полный цикл запроса/ответа: DNS-разрешение, TCP-подключение, TLS-рукопожатие, отправленные заголовки запроса и полученные заголовки ответа. Это самый полезный флаг для отладки.

2. 2

   Проверьте HTTP-код статуса

   Запустите curl -o /dev/null -s -w "%{http_code}" URL, чтобы получить только HTTP-код статуса (200, 404, 500 и т.д.) без тела ответа. Удобно для быстрых проверок и скриптов.

3. 3

   Тихий режим с отображением ошибок

   Запустите curl -sS URL, чтобы скрыть прогресс-бар (-s), но показывать ошибки (-S). Идеально для скриптов, где нужен чистый вывод, но важно видеть сбои.

Часто задаваемые вопросы