Коди помилок 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, переконайтеся, що порт контейнера опублікований. Спробуйте з детальним виводом: 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. Використовуйте детальний режим, щоб побачити, де зависає: 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 — помилка 35 типово вказує на збій рукостискання на рівні протоколу.

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

Помилка 56: Збій отримання — З'єднання скинуто

Що це означає

У терміналі відображається curl: (56) Recv failure: Connection reset by peer. З'єднання було успішно встановлено, але отримання даних не вдалося — сервер несподівано закрив або скинув з'єднання під час передачі.

Причини

Це часто трапляється, коли: сервер аварійно завершує роботу або перезапускається під час передачі, балансувальник навантаження або проксі розриває з'єднання (тайм-аут простою, занадто великий запит), фаєрвол розриває довготривалі з'єднання, сервер має тайм-аут keep-alive коротший за очікуваний або є порушення мережі між клієнтом та сервером.

Як виправити

Спробуйте повторити запит — тимчасові проблеми мережі є найпоширенішою причиною. Використовуйте детальний режим: 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 (центрів сертифікації). TLS-рукостискання на рівні протоколу завершилося, але перевірка сертифіката не пройшла.

Причини

Найпоширеніші причини: сервер використовує самопідписаний сертифікат, сертифікат прострочений, ланцюжок сертифікатів неповний (відсутні проміжні сертифікати), набір CA curl застарів (часто на старих системах або в 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). Ідеально для скриптів, де потрібен чистий вивід, але необхідно відстежувати збої.

Поширені запитання