Kody błędów curl: Kompletny przewodnik

Szybka tabela referencyjna

Błąd 6: Nie można rozwiązać hosta

Co to oznacza

W terminalu widzisz curl: (6) Could not resolve host. curl nie mógł rozwiązać nazwy hosta na adres IP — wyszukiwanie DNS nie powiodło się przed jakąkolwiek próbą połączenia.

Przyczyny

Najczęstsze przyczyny to: literówka w nazwie hosta (np. curl https://apiexample.com zamiast api.example.com), problemy z serwerem DNS (skonfigurowany DNS nie działa lub jest nieosiągalny), brak połączenia sieciowego (Wi-Fi rozłączone, VPN nie podłączony) lub domena faktycznie nie istnieje.

Jak naprawić

Najpierw sprawdź, czy URL jest poprawny. Następnie przetestuj rozwiązywanie DNS bezpośrednio: nslookup api.example.com lub dig api.example.com. Jeśli DNS zawodzi, spróbuj innego serwera DNS: curl --dns-servers 8.8.8.8 https://api.example.com. Sprawdź /etc/resolv.conf lub ustawienia sieciowe. Jeśli jesteś za firmowym VPN, upewnij się, że wewnętrzny DNS może rozwiązać hosta.

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

Błąd 7: Nie udało się nawiązać połączenia

Co to oznacza

W terminalu widzisz curl: (7) Failed to connect to host port: Connection refused. curl rozwiązał nazwę hosta, ale nie mógł nawiązać połączenia TCP z serwerem — połączenie zostało aktywnie odrzucone lub przekroczyło limit czasu na poziomie TCP.

Przyczyny

Typowe przyczyny to: serwer jest wyłączony lub nie działa, zapora sieciowa blokuje port (sprawdź zarówno lokalną, jak i serwerową zaporę), nieprawidłowy port (np. usługa działa na 8080, a łączysz się z 443), lub bufor nasłuchu serwera jest pełny przy dużym obciążeniu.

Jak naprawić

Sprawdź, czy serwer działa: ping api.example.com i telnet api.example.com 443. Sprawdź, czy właściwy port jest otwarty: nmap -p 443 api.example.com. Tymczasowo wyłącz lokalną zaporę do testów. Jeśli używasz Dockera, upewnij się, że port kontenera jest opublikowany. Spróbuj z trybem verbose: curl -v https://api.example.com, aby zobaczyć dokładnie, gdzie połączenie zawodzi.

$ curl https://localhost:8080/api

Błąd 22: HTTP zwrócił błąd

Co to oznacza

W terminalu widzisz curl: (22) The requested URL returned error. Serwer zwrócił kod statusu HTTP błędu (4xx lub 5xx), a curl został wywołany z flagą -f lub --fail, która nakazuje curl traktować błędy HTTP jako niepowodzenia.

Przyczyny

Błąd jest wywoływany przez kody statusu HTTP, takie jak 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) lub 500 (Internal Server Error) — ale tylko gdy użyto --fail. Bez --fail curl kończy się kodem 0 nawet przy błędach HTTP. Typowe przyczyny: nieprawidłowy URL, brak uwierzytelnienia, niewystarczające uprawnienia lub błędy po stronie serwera.

Jak naprawić

Uruchom curl bez --fail, aby zobaczyć pełną treść odpowiedzi — często zawiera ona właściwy komunikat o błędzie. Sprawdź kod statusu HTTP: curl -w "%{http_code}" -o /dev/null -s URL. Dla 401/403: zweryfikuj token uwierzytelniający lub klucz API. Dla 404: sprawdź dokładnie ścieżkę URL. Dla 500: problem jest po stronie serwera.

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

Błąd 28: Przekroczono limit czasu operacji

Co to oznacza

W terminalu widzisz curl: (28) Operation timed out lub curl: (28) Connection timed out. Operacja trwała dłużej niż dozwolony czas. Jest to najczęstszy błąd curl — może wystąpić podczas rozwiązywania DNS, połączenia TCP, handshake SSL lub transferu danych.

Przyczyny

Typowe przyczyny to: wolny lub przeciążony serwer nie odpowiadający w czasie, przeciążenie sieci lub utrata pakietów, zapora sieciowa cicho odrzucająca pakiety (bez odrzucenia, po prostu cisza), zbyt rygorystyczne wartości timeout ustawione przez --connect-timeout lub --max-time, lub błędna konfiguracja proxy powodująca opóźnienia.

Jak naprawić

Zwiększ timeout: curl --connect-timeout 30 --max-time 120 URL. Użyj trybu verbose, aby zobaczyć, gdzie się zatrzymuje: curl -v URL. Przetestuj opóźnienie sieci: ping api.example.com i traceroute api.example.com. Jeśli jesteś za proxy, spróbuj go ominąć: curl --noproxy '*' URL. Przy dużych transferach plików rozważ użycie --retry 3 z --retry-delay 5.

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

Błąd 35: Błąd połączenia SSL

Co to oznacza

W terminalu widzisz curl: (35) SSL connect error. Handshake SSL/TLS nie powiódł się — curl nie mógł nawiązać bezpiecznego połączenia z serwerem.

Przyczyny

Typowe przyczyny: niezgodność wersji TLS (serwer wymaga TLS 1.3, ale Twój curl obsługuje tylko TLS 1.2), niezgodność zestawów szyfrów, błędna konfiguracja SSL serwera (wygasły certyfikat przedstawiony podczas handshake, niekompletny łańcuch), serwer nie obsługuje HTTPS na danym porcie, lub proxy lub zapora przechwytuje połączenie SSL (MITM).

Jak naprawić

Wymuś konkretną wersję TLS: curl --tlsv1.2 URL lub curl --tlsv1.3 URL. Sprawdź, co obsługuje serwer: openssl s_client -connect api.example.com:443. Zaktualizuj curl i OpenSSL do najnowszych wersji. Jeśli serwer używa certyfikatu self-signed, zwykle jest to błąd 60 — błąd 35 zazwyczaj wskazuje na problem handshake na poziomie protokołu.

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

Błąd 56: Niepowodzenie odbioru — Połączenie zostało zresetowane

Co to oznacza

W terminalu widzisz curl: (56) Recv failure: Connection reset by peer. Połączenie zostało nawiązane pomyślnie, ale odbiór danych nie powiódł się — serwer zamknął lub zresetował połączenie nieoczekiwanie podczas transferu.

Przyczyny

Często zdarza się, gdy: serwer ulega awarii lub restartuje się w trakcie transferu, load balancer lub proxy przerywa połączenie (timeout bezczynności, zbyt duże żądanie), zapora kończy długotrwałe połączenia, serwer ma krótszy timeout keep-alive niż oczekiwano, lub występuje zakłócenie sieci między klientem a serwerem.

Jak naprawić

Spróbuj ponowić żądanie — przejściowe problemy sieciowe są najczęstszą przyczyną. Użyj trybu verbose: curl -v URL, aby zobaczyć dokładny punkt awarii. Jeśli błąd występuje podczas dużych uploadów, spróbuj chunked transfer: curl -H "Transfer-Encoding: chunked" URL. Dla operacji Git pokazujących RPC failed; curl 56, zwiększ bufor: git config http.postBuffer 524288000.

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

Błąd 60: Problem z certyfikatem SSL

Co to oznacza

W terminalu widzisz curl: (60) SSL certificate problem: unable to get local issuer certificate. curl nie mógł zweryfikować certyfikatu SSL serwera wobec swojego pakietu CA (Certificate Authority). Handshake TLS zakończył się na poziomie protokołu, ale walidacja certyfikatu nie powiodła się.

Przyczyny

Najczęstsze przyczyny: serwer używa certyfikatu self-signed, certyfikat wygasł, łańcuch certyfikatów jest niekompletny (brakuje certyfikatów pośrednich), pakiet CA curl jest przestarzały (częste na starszych systemach lub w kontenerach Docker), lub Common Name / SAN certyfikatu nie pasuje do żądanej nazwy hosta.

Jak naprawić

Zaktualizuj pakiet CA: curl --cacert /path/to/cacert.pem URL. Pobierz zaktualizowany pakiet z https://curl.se/ca/cacert.pem. Aby zdiagnozować: openssl s_client -connect api.example.com:443 -showcerts. Dla certyfikatów self-signed w środowisku deweloperskim użyj curl -k URL (nigdy w produkcji — wyłącza to całą weryfikację certyfikatów). W Dockerze zainstaluj pakiet ca-certificates.

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

Inne kody błędów

Jak debugować błędy curl

Gdy curl zawodzi, te trzy flagi pomagają szybko zidentyfikować przyczynę — od rozwiązywania DNS po handshake SSL po ładunek odpowiedzi.

1. 1

   Włącz szczegółowe wyjście

   Uruchom curl -v URL, aby zobaczyć pełny cykl żądanie/odpowiedź: rozwiązywanie DNS, połączenie TCP, handshake TLS, wysłane nagłówki żądania i odebrane nagłówki odpowiedzi. Jest to najużyteczniejsza flaga do debugowania.

2. 2

   Sprawdź kod statusu HTTP

   Uruchom curl -o /dev/null -s -w "%{http_code}" URL, aby uzyskać sam kod statusu HTTP (200, 404, 500 itd.) bez treści odpowiedzi. Przydatne do szybkich testów kondycji i skryptów.

3. 3

   Pokaż błędy cicho

   Uruchom curl -sS URL, aby ukryć pasek postępu (-s), ale nadal wyświetlać błędy (-S). Idealne do skryptów, gdzie chcesz czystego wyjścia, ale musisz wykrywać awarie.

Najczęściej zadawane pytania