Chybové kódy curl: Kompletná referenčná príručka

Rýchla referenčná tabuľka

Chyba 6: Nepodarilo sa rozlíšiť hostiteľa

Čo to znamená

Váš terminál zobrazuje curl: (6) Could not resolve host. curl nedokázal rozlíšiť názov hostiteľa na IP adresu — DNS vyhľadávanie zlyhalo ešte pred pokusom o spojenie.

Príčiny

Najčastejšie príčiny sú: preklep v názve hostiteľa (napr. curl https://apiexample.com namiesto api.example.com), problémy s DNS serverom (váš nakonfigurovaný DNS je nedostupný alebo nefunkčný), žiadne sieťové pripojenie (Wi-Fi odpojené, VPN nepripojená), alebo doména skutočne neexistuje.

Ako opraviť

Najprv skontrolujte, či je URL správna. Potom otestujte DNS rozlíšenie priamo: nslookup api.example.com alebo dig api.example.com. Ak DNS zlyhá, skúste iný DNS server: curl --dns-servers 8.8.8.8 https://api.example.com. Skontrolujte váš /etc/resolv.conf alebo nastavenia siete. Ak ste za firemnou VPN, uistite sa, že interný DNS dokáže rozlíšiť hostiteľa.

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

Chyba 7: Nepodarilo sa pripojiť

Čo to znamená

Váš terminál zobrazuje curl: (7) Failed to connect to host port: Connection refused. curl rozlíšil názov hostiteľa, ale nedokázal nadviazať TCP spojenie so serverom — spojenie bolo aktívne odmietnuté alebo vypršal čas na úrovni TCP.

Príčiny

Bežné príčiny zahŕňajú: server je vypnutý alebo nebeží, firewall blokuje port (skontrolujte lokálny aj serverový firewall), port je nesprávny (napr. služba beží na 8080, ale vy sa pripájate na 443), alebo je fronta spojení servera plná pri vysokej záťaži.

Ako opraviť

Overte, že server beží: ping api.example.com a telnet api.example.com 443. Skontrolujte, či je správny port otvorený: nmap -p 443 api.example.com. Dočasne vypnite lokálny firewall na test. Ak používate Docker, uistite sa, že port kontajnera je publikovaný. Skúste verbose režim: curl -v https://api.example.com na presné zistenie, kde spojenie zlyháva.

$ curl https://localhost:8080/api

Chyba 22: HTTP vrátil chybu

Čo to znamená

Váš terminál zobrazuje curl: (22) The requested URL returned error. Server vrátil HTTP chybový stavový kód (4xx alebo 5xx) a curl bol spustený s -f alebo --fail, čo hovorí curlu, aby HTTP chyby považoval za zlyhania.

Príčiny

Chybu spúšťajú HTTP stavové kódy ako 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) alebo 500 (Internal Server Error) — ale iba keď je použitý --fail. Bez --fail curl ukončí s kódom 0 aj pri HTTP chybách. Bežné príčiny: nesprávna URL, chýbajúca autentifikácia, nedostatočné oprávnenia alebo chyby na strane servera.

Ako opraviť

Spustite curl bez --fail na zobrazenie celého tela odpovede — často obsahuje skutočnú chybovú správu. Skontrolujte HTTP stavový kód: curl -w "%{http_code}" -o /dev/null -s URL. Pre 401/403: overte váš auth token alebo API kľúč. Pre 404: skontrolujte cestu URL. Pre 500: problém je na strane servera.

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

Chyba 28: Operácia vypršala

Čo to znamená

Váš terminál zobrazuje curl: (28) Operation timed out alebo curl: (28) Connection timed out. Operácia trvala dlhšie ako povolený čas. Toto je najčastejšia chyba curl — môže nastať počas DNS rozlíšenia, TCP spojenia, SSL handshake alebo prenosu dát.

Príčiny

Typické príčiny zahŕňajú: pomalý alebo preťažený server neodpovedajúci včas, preťaženie siete alebo strata paketov, firewall ticho zahadzuje pakety (žiadne odmietnutie, len ticho), príliš prísne hodnoty timeout nastavené pomocou --connect-timeout alebo --max-time, alebo nesprávna konfigurácia proxy spôsobujúca oneskorenia.

Ako opraviť

Zvýšte timeout: curl --connect-timeout 30 --max-time 120 URL. Použite verbose režim na zistenie, kde to visí: curl -v URL. Otestujte latenciu siete: ping api.example.com a traceroute api.example.com. Ak ste za proxy, skúste ho obísť: curl --noproxy '*' URL. Pre veľké prenosy súborov zvážte použitie --retry 3 s --retry-delay 5.

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

Chyba 35: Chyba SSL spojenia

Čo to znamená

Váš terminál zobrazuje curl: (35) SSL connect error. SSL/TLS handshake zlyhal — curl nedokázal nadviazať bezpečné spojenie so serverom.

Príčiny

Bežné príčiny: nezhoda verzie TLS (server vyžaduje TLS 1.3, ale váš curl podporuje iba TLS 1.2), nekompatibilita šifrovacích sád, nesprávna SSL konfigurácia servera (expirovaný certifikát počas handshake, neúplný reťazec), server v skutočnosti nepodporuje HTTPS na danom porte, alebo proxy alebo firewall zachytáva SSL spojenie (MITM).

Ako opraviť

Vynúťte konkrétnu verziu TLS: curl --tlsv1.2 URL alebo curl --tlsv1.3 URL. Skontrolujte, čo server podporuje: openssl s_client -connect api.example.com:443. Aktualizujte curl a OpenSSL na najnovšie verzie. Ak server používa self-signed certifikát, ide zvyčajne o chybu 60 — chyba 35 typicky indikuje zlyhanie handshake na úrovni protokolu.

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

Chyba 56: Zlyhanie príjmu — Spojenie bolo resetované

Čo to znamená

Váš terminál zobrazuje curl: (56) Recv failure: Connection reset by peer. Spojenie bolo nadviazané úspešne, ale príjem dát zlyhal — server nečakane zatvoril alebo resetoval spojenie počas prenosu.

Príčiny

Toto sa často stáva, keď: server zlyhá alebo sa reštartuje počas prenosu, load balancer alebo proxy ukončí spojenie (timeout nečinnosti, príliš veľká požiadavka), firewall ukončuje dlhodobé spojenia, server má kratší keep-alive timeout ako sa očakávalo, alebo nastáva výpadok siete medzi klientom a serverom.

Ako opraviť

Skúste požiadavku znova — prechodné problémy siete sú najčastejšou príčinou. Použite verbose režim: curl -v URL na zistenie presného bodu zlyhania. Ak sa chyba vyskytuje pri veľkých uploadoch, skúste chunked prenos: curl -H "Transfer-Encoding: chunked" URL. Pre Git operácie zobrazujúce RPC failed; curl 56, zvýšte buffer: git config http.postBuffer 524288000.

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

Chyba 60: Problém s SSL certifikátom

Čo to znamená

Váš terminál zobrazuje curl: (60) SSL certificate problem: unable to get local issuer certificate. curl nedokázal overiť SSL certifikát servera voči svojmu CA (Certificate Authority) balíku. TLS handshake sa dokončil na úrovni protokolu, ale overenie certifikátu zlyhalo.

Príčiny

Najčastejšie príčiny: server používa self-signed certifikát, certifikát vypršal, reťazec certifikátov je neúplný (chýbajúce intermediate certifikáty), CA balík curlu je zastaraný (bežné na starších systémoch alebo v Docker kontajneroch), alebo Common Name / SAN certifikátu sa nezhoduje s požadovaným názvom hostiteľa.

Ako opraviť

Aktualizujte CA balík: curl --cacert /path/to/cacert.pem URL. Stiahnite aktualizovaný balík z https://curl.se/ca/cacert.pem. Na diagnostiku: openssl s_client -connect api.example.com:443 -showcerts. Pre self-signed certifikáty vo vývojovom prostredí použite curl -k URL (nikdy v produkcii — vypína všetky overenia certifikátov). V Dockeri nainštalujte balík ca-certificates.

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

Ostatné chybové kódy

Ako ladiť chyby curl

Keď curl zlyhá, tieto tri príznaky vám pomôžu rýchlo identifikovať príčinu — od DNS rozlíšenia po SSL handshake až po telo odpovede.

1. 1

   Zapnite podrobný výstup

   Spustite curl -v URL na zobrazenie celého cyklu požiadavky/odpovede: DNS rozlíšenie, TCP spojenie, TLS handshake, odoslané hlavičky požiadavky a prijaté hlavičky odpovede. Toto je najužitočnejší ladiaci príznak.

2. 2

   Skontrolujte HTTP stavový kód

   Spustite curl -o /dev/null -s -w "%{http_code}" URL na získanie iba HTTP stavového kódu (200, 404, 500 atď.) bez tela odpovede. Užitočné pre rýchle kontroly stavu a skriptovanie.

3. 3

   Zobrazte chyby potichu

   Spustite curl -sS URL na potlačenie indikátora priebehu (-s), ale stále zobrazí chyby (-S). Ideálne pre skripty, kde chcete čistý výstup, ale potrebujete zachytiť zlyhania.

Často kladené otázky