Кодове за грешки на 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 обикновено означава неуспех на хендшейка на ниво протокол.

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

Грешка 56: Грешка при получаване — Връзката беше нулирана

Какво означава

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

Причини

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

Как да се поправи

Опитайте заявката отново — преходните мрежови проблеми са най-честата причина. Използвайте подробен режим: curl -v URL, за да видите точната точка на провал. Ако грешката се появява при големи качвания, опитайте частично прехвърляне: 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 пакетът на 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). Идеално за скриптове, където искате чист изход, но трябва да улавяте грешки.

Често задавани въпроси