Chybové kódy curl: Kompletní přehled

Rychlá referenční tabulka

Chyba 6: Nelze přeložit hostname

Co to znamená

Terminál zobrazí curl: (6) Could not resolve host. curl nemohl přeložit hostname na IP adresu — DNS dotaz selhal ještě před pokusem o připojení.

Příčiny

Nejčastějšími příčinami jsou: překlep v hostname (např. curl https://apiexample.com místo api.example.com), problémy s DNS serverem (váš nakonfigurovaný DNS je nedostupný), absence síťového připojení (odpojená Wi-Fi, nepřipojená VPN) nebo doména skutečně neexistuje.

Jak opravit

Nejprve ověřte, že URL je správná. Poté otestujte DNS překlad přímo: nslookup api.example.com nebo dig api.example.com. Pokud DNS selže, zkuste jiný DNS server: curl --dns-servers 8.8.8.8 https://api.example.com. Zkontrolujte /etc/resolv.conf nebo nastavení sítě. Pokud jste za firemní VPN, ujistěte se, že interní DNS může přeložit daný host.

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

Chyba 7: Připojení selhalo

Co to znamená

Terminál zobrazí curl: (7) Failed to connect to host port: Connection refused. curl přeložil hostname, ale nemohl navázat TCP spojení se serverem — připojení bylo aktivně odmítnuto nebo vypršel časový limit na úrovni TCP.

Příčiny

Běžné příčiny zahrnují: server je vypnutý nebo neběží, firewall blokuje port (zkontrolujte lokální i serverový firewall), špatný port (např. služba běží na 8080, ale připojujete se na 443) nebo je fronta serveru plná při vysoké zátěži.

Jak opravit

Ověřte, že server běží: ping api.example.com a telnet api.example.com 443. Zkontrolujte, zda je správný port otevřený: nmap -p 443 api.example.com. Dočasně vypněte lokální firewall pro test. Pokud používáte Docker, ujistěte se, že port kontejneru je publikován. Zkuste verbose režim: curl -v https://api.example.com abyste viděli, kde přesně připojení selhává.

$ curl https://localhost:8080/api

Chyba 22: HTTP vrátilo chybu

Co to znamená

Terminál zobrazí curl: (22) The requested URL returned error. Server vrátil stavový kód HTTP chyby (4xx nebo 5xx) a curl byl spuštěn s příznakem -f nebo --fail, který říká curl, aby HTTP chyby považoval za selhání.

Příčiny

Chyba je vyvolána HTTP stavovými kódy jako 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) nebo 500 (Internal Server Error) — ale pouze při použití --fail. Bez --fail curl skončí s kódem 0 i při HTTP chybách. Běžné příčiny: špatná URL, chybějící autentizace, nedostatečná oprávnění nebo chyby na straně serveru.

Jak opravit

Spusťte curl bez --fail abyste viděli celé tělo odpovědi — často obsahuje skutečnou chybovou zprávu. Zkontrolujte HTTP stavový kód: curl -w "%{http_code}" -o /dev/null -s URL. Pro 401/403: ověřte svůj auth token nebo API klíč. Pro 404: znovu zkontrolujte cestu URL. Pro 500: problém je na straně serveru.

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

Chyba 28: Vypršel časový limit operace

Co to znamená

Terminál zobrazí curl: (28) Operation timed out nebo curl: (28) Connection timed out. Operace trvala déle než povolený čas. Toto je nejčastější chyba curl — může nastat během DNS překladu, TCP připojení, SSL handshake nebo přenosu dat.

Příčiny

Typické příčiny zahrnují: pomalý nebo přetížený server, který neodpovídá včas, zahlcení sítě nebo ztráta paketů, firewall tiše zahazuje pakety (žádné odmítnutí, pouze ticho), příliš přísné hodnoty timeout nastavené pomocí --connect-timeout nebo --max-time nebo špatná konfigurace proxy způsobující zpoždění.

Jak opravit

Zvyšte timeout: curl --connect-timeout 30 --max-time 120 URL. Použijte verbose režim abyste viděli, kde to zasekává: curl -v URL. Otestujte síťovou latenci: ping api.example.com a traceroute api.example.com. Pokud jste za proxy, zkuste ji obějit: curl --noproxy '*' URL. Pro velké přenosy souborů zvažte použití --retry 3 s --retry-delay 5.

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

Chyba 35: Chyba SSL připojení

Co to znamená

Terminál zobrazí curl: (35) SSL connect error. SSL/TLS handshake selhal — curl nemohl navázat zabezpečené spojení se serverem.

Příčiny

Běžné příčiny: nesoulad verze TLS (server vyžaduje TLS 1.3, ale váš curl podporuje pouze TLS 1.2), nekompatibilita šifrovacích sad, špatná SSL konfigurace serveru (vypršelý certifikát prezentovaný během handshake, neúplný řetězec), server ve skutečnosti nepodporuje HTTPS na daném portu nebo proxy či firewall zachytává SSL spojení (MITM).

Jak opravit

Vynuťte konkrétní verzi TLS: curl --tlsv1.2 URL nebo curl --tlsv1.3 URL. Zkontrolujte, co server podporuje: openssl s_client -connect api.example.com:443. Aktualizujte curl a OpenSSL na nejnovější verze. Pokud server používá self-signed certifikát, jedná se obvykle o chybu 60 — chyba 35 typicky indikuje selhání handshake na úrovni protokolu.

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

Chyba 56: Selhání příjmu — Spojení bylo resetováno

Co to znamená

Terminál zobrazí curl: (56) Recv failure: Connection reset by peer. Spojení bylo úspěšně navázáno, ale příjem dat selhal — server nečekaně uzavřel nebo resetoval spojení během přenosu.

Příčiny

K tomu často dochází, když: server spadne nebo se restartuje uprostřed přenosu, load balancer nebo proxy ukončí spojení (timeout nečinnosti, příliš velký požadavek), firewall ukončuje dlouhotrvající spojení, server má kratší keep-alive timeout než se očekává nebo dojde k narušení sítě mezi klientem a serverem.

Jak opravit

Zkuste požadavek znovu — přechodné síťové problémy jsou nejčastější příčinou. Použijte verbose režim: curl -v URL abyste viděli přesný bod selhání. Pokud chyba nastává při velkých uploadzích, zkuste chunked přenos: curl -H "Transfer-Encoding: chunked" URL. Pro Git operace zobrazující RPC failed; curl 56 zvětšete buffer: git config http.postBuffer 524288000.

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

Chyba 60: Problém s SSL certifikátem

Co to znamená

Terminál zobrazí curl: (60) SSL certificate problem: unable to get local issuer certificate. curl nemohl ověřit SSL certifikát serveru oproti jeho CA (Certifikační Autorita) balíčku. TLS handshake se dokončil na úrovni protokolu, ale ověření certifikátu selhalo.

Příčiny

Nejčastější příčiny: server používá self-signed certifikát, certifikát vypršel, řetězec certifikátů je neúplný (chybí mezilehlé certifikáty), CA balíček curl je zastaralý (běžné na starších systémech nebo v Docker kontejnerech) nebo Common Name / SAN certifikátu neodpovídá požadovanému hostname.

Jak opravit

Aktualizujte CA balíček: curl --cacert /path/to/cacert.pem URL. Stáhněte aktualizovaný balíček z https://curl.se/ca/cacert.pem. Pro diagnostiku: openssl s_client -connect api.example.com:443 -showcerts. Pro self-signed certifikáty ve vývojovém prostředí použijte curl -k URL (nikdy v produkci — vypíná veškeré ověřování certifikátů). V Dockeru nainstalujte balíček ca-certificates.

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

Ostatní chybové kódy

Jak ladit chyby curl

Když curl selže, tyto tři příznaky vám pomohou rychle identifikovat příčinu — od DNS překladu přes SSL handshake až po obsah odpovědi.

1. 1

   Zapněte podrobný výstup

   Spusťte curl -v URL pro zobrazení celého cyklu požadavek/odpověď: DNS překlad, TCP připojení, TLS handshake, odeslané hlavičky požadavku a přijaté hlavičky odpovědi. Toto je nejužitečnější ladicí příznak.

2. 2

   Zkontrolujte HTTP stavový kód

   Spusťte curl -o /dev/null -s -w "%{http_code}" URL pro získání samotného HTTP stavového kódu (200, 404, 500 atd.) bez těla odpovědi. Užitečné pro rychlé kontroly stavu a skriptování.

3. 3

   Zobrazujte chyby tiše

   Spusťte curl -sS URL pro potlačení ukazatele průběhu (-s), ale se zobrazením chyb (-S). Ideální pro skripty, kde chcete čistý výstup, ale potřebujete zachytit selhání.

Často kladené dotazy