curl-Fehlercodes: Vollständige Referenz

Wenn ein curl-Befehl fehlschlägt, gibt er einen numerischen Exit-Code (auch curl-Fehlercode genannt) zurück, der die Art des Fehlers identifiziert. Sie können den curl-Exit-Code überprüfen, indem Sie echo $? unmittelbar nach dem curl-Befehl ausführen (oder $LASTEXITCODE in PowerShell). Der Exit-Code 0 bedeutet Erfolg; jede andere Zahl weist auf ein spezifisches Problem hin — von DNS-Auflösungsfehlern und Verbindungs-Timeouts bis hin zu SSL-Zertifikatsproblemen. Diese Seite ist eine vollständige Referenz der häufigsten curl-Fehlercodes mit Erklärungen, Ursachen und Lösungen. Wenn Sie mit curl-Befehlen in Ihrem Code arbeiten, fügen Sie diese in curl2code ein, um sie in die Programmiersprache Ihrer Wahl zu konvertieren.

Schnellreferenz-Tabelle

Exit-Code	Fehlername	Beschreibung
0	CURLE_OK	Erfolg. Die Operation wurde ohne Fehler abgeschlossen.
1	CURLE_UNSUPPORTED_PROTOCOL	Nicht unterstütztes Protokoll. Die URL verwendet ein Protokoll, für das curl keine Unterstützung bietet.
3	CURLE_URL_MALFORMAT	Fehlerhafte URL. Die URL-Syntax ist ungültig oder konnte nicht analysiert werden.
5	CURLE_COULDNT_RESOLVE_PROXY	Proxy konnte nicht aufgelöst werden. Der angegebene Proxy-Hostname konnte nicht aufgelöst werden.
6	CURLE_COULDNT_RESOLVE_HOST	DNS-Lookup fehlgeschlagen — der Hostname konnte nicht in eine IP-Adresse aufgelöst werden.
7	CURLE_COULDNT_CONNECT	TCP-Verbindung fehlgeschlagen — Server ist offline, Port ist blockiert oder Firewall lehnt Verbindungen ab.
18	CURLE_PARTIAL_FILE	Teilweise Datei. Die Übertragung wurde unterbrochen und nur ein Teil der Datei wurde empfangen.
22	CURLE_HTTP_RETURNED_ERROR	Server gab einen HTTP-Fehler (4xx/5xx) zurück und das Flag --fail wurde verwendet.
23	CURLE_WRITE_ERROR	Schreibfehler. curl konnte die empfangenen Daten nicht auf die Festplatte schreiben (Zugriff verweigert oder Festplatte voll).
28	CURLE_OPERATION_TIMEDOUT	Die Operation hat die maximal zulässige Zeit überschritten (DNS, Verbindung oder Übertragung).
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS-Handshake fehlgeschlagen — Protokollversion oder Cipher-Suite stimmen nicht überein.
37	CURLE_FILE_COULDNT_READ_FILE	Datei konnte nicht gelesen werden. Eine in der Anfrage referenzierte lokale Datei konnte nicht geöffnet oder gelesen werden.
52	CURLE_GOT_NOTHING	Leere Antwort vom Server. Der Server hat die Verbindung geschlossen, ohne Daten zu senden.
56	CURLE_RECV_ERROR	Verbindung wurde zurückgesetzt — der Server hat die Verbindung während der Datenübertragung unterbrochen.
60	CURLE_SSL_CACERT	SSL-Zertifikatsprüfung fehlgeschlagen — abgelaufen, selbstsigniert oder CA-Bundle ist veraltet.
77	CURLE_SSL_CACERT_BADFILE	SSL-CA-Zertifikatsproblem. Die angegebene CA-Zertifikatsdatei konnte nicht gelesen oder analysiert werden.
92	CURLE_HTTP2_STREAM	HTTP/2-Stream-Fehler. Während der Übertragung ist ein Fehler auf HTTP/2-Protokollebene im Stream aufgetreten.

0CURLE_OK

Erfolg. Die Operation wurde ohne Fehler abgeschlossen.

1CURLE_UNSUPPORTED_PROTOCOL

Nicht unterstütztes Protokoll. Die URL verwendet ein Protokoll, für das curl keine Unterstützung bietet.

3CURLE_URL_MALFORMAT

Fehlerhafte URL. Die URL-Syntax ist ungültig oder konnte nicht analysiert werden.

5CURLE_COULDNT_RESOLVE_PROXY

Proxy konnte nicht aufgelöst werden. Der angegebene Proxy-Hostname konnte nicht aufgelöst werden.

6CURLE_COULDNT_RESOLVE_HOST

DNS-Lookup fehlgeschlagen — der Hostname konnte nicht in eine IP-Adresse aufgelöst werden.

7CURLE_COULDNT_CONNECT

TCP-Verbindung fehlgeschlagen — Server ist offline, Port ist blockiert oder Firewall lehnt Verbindungen ab.

18CURLE_PARTIAL_FILE

Teilweise Datei. Die Übertragung wurde unterbrochen und nur ein Teil der Datei wurde empfangen.

22CURLE_HTTP_RETURNED_ERROR

Server gab einen HTTP-Fehler (4xx/5xx) zurück und das Flag --fail wurde verwendet.

23CURLE_WRITE_ERROR

Schreibfehler. curl konnte die empfangenen Daten nicht auf die Festplatte schreiben (Zugriff verweigert oder Festplatte voll).

28CURLE_OPERATION_TIMEDOUT

Die Operation hat die maximal zulässige Zeit überschritten (DNS, Verbindung oder Übertragung).

35CURLE_SSL_CONNECT_ERROR

SSL/TLS-Handshake fehlgeschlagen — Protokollversion oder Cipher-Suite stimmen nicht überein.

37CURLE_FILE_COULDNT_READ_FILE

Datei konnte nicht gelesen werden. Eine in der Anfrage referenzierte lokale Datei konnte nicht geöffnet oder gelesen werden.

52CURLE_GOT_NOTHING

Leere Antwort vom Server. Der Server hat die Verbindung geschlossen, ohne Daten zu senden.

56CURLE_RECV_ERROR

Verbindung wurde zurückgesetzt — der Server hat die Verbindung während der Datenübertragung unterbrochen.

60CURLE_SSL_CACERT

SSL-Zertifikatsprüfung fehlgeschlagen — abgelaufen, selbstsigniert oder CA-Bundle ist veraltet.

77CURLE_SSL_CACERT_BADFILE

SSL-CA-Zertifikatsproblem. Die angegebene CA-Zertifikatsdatei konnte nicht gelesen oder analysiert werden.

92CURLE_HTTP2_STREAM

HTTP/2-Stream-Fehler. Während der Übertragung ist ein Fehler auf HTTP/2-Protokollebene im Stream aufgetreten.

Fehler 6: Host konnte nicht aufgelöst werden

Bedeutung: Ihr Terminal zeigt curl: (6) Could not resolve host an. curl konnte den Hostnamen nicht in eine IP-Adresse auflösen — der DNS-Lookup schlug fehl, bevor eine Verbindung versucht wurde.
Ursachen: Die häufigsten Ursachen sind: ein Tippfehler im Hostnamen (z. B. curl https://apiexample.com statt api.example.com), DNS-Server-Probleme (Ihr konfigurierter DNS ist offline oder nicht erreichbar), keine Netzwerkverbindung (WLAN getrennt, VPN nicht verbunden) oder die Domain existiert tatsächlich nicht.
Lösung: Überprüfen Sie zuerst, ob die URL korrekt ist. Testen Sie dann die DNS-Auflösung direkt: nslookup api.example.com oder dig api.example.com. Wenn DNS fehlschlägt, versuchen Sie einen anderen DNS-Server: curl --dns-servers 8.8.8.8 https://api.example.com. Überprüfen Sie Ihre /etc/resolv.conf oder Netzwerkeinstellungen. Wenn Sie sich hinter einem Unternehmens-VPN befinden, stellen Sie sicher, dass der interne DNS den Host auflösen kann.

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

Fehler 7: Verbindung fehlgeschlagen

Bedeutung: Ihr Terminal zeigt curl: (7) Failed to connect to host port: Connection refused an. curl hat den Hostnamen aufgelöst, konnte aber keine TCP-Verbindung zum Server herstellen — die Verbindung wurde aktiv abgelehnt oder es kam zu einem Timeout auf TCP-Ebene.
Ursachen: Häufige Ursachen sind: der Server ist offline oder läuft nicht, eine Firewall blockiert den Port (überprüfen Sie sowohl lokale als auch serverseitige Firewalls), der Port ist falsch (z. B. läuft der Dienst auf 8080, aber Sie verbinden sich mit 443) oder der Listen-Backlog des Servers ist bei hoher Last voll.
Lösung: Überprüfen Sie, ob der Server läuft: ping api.example.com und telnet api.example.com 443. Prüfen Sie, ob der richtige Port offen ist: nmap -p 443 api.example.com. Deaktivieren Sie testweise die lokale Firewall. Wenn Sie Docker verwenden, stellen Sie sicher, dass der Container-Port veröffentlicht wurde. Versuchen Sie es mit dem Verbose-Modus: curl -v https://api.example.com, um genau zu sehen, wo die Verbindung fehlschlägt.

$ curl https://localhost:8080/api

Fehler 22: HTTP gab Fehler zurück

Bedeutung: Ihr Terminal zeigt curl: (22) The requested URL returned error an. Der Server hat einen HTTP-Fehlerstatuscode (4xx oder 5xx) zurückgegeben und curl wurde mit -f oder --fail aufgerufen, was curl anweist, HTTP-Fehler als Fehlschläge zu behandeln.
Ursachen: Der Fehler wird durch HTTP-Statuscodes wie 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) oder 500 (Internal Server Error) ausgelöst — aber nur, wenn --fail verwendet wird. Ohne --fail beendet curl den Vorgang auch bei HTTP-Fehlern mit Code 0. Häufige Ursachen: falsche URL, fehlende Authentifizierung, unzureichende Berechtigungen oder serverseitige Fehler.
Lösung: Führen Sie curl ohne --fail aus, um den vollständigen Antwort-Body zu sehen — dieser enthält oft die eigentliche Fehlermeldung. Überprüfen Sie den HTTP-Statuscode: curl -w "%{http_code}" -o /dev/null -s URL. Bei 401/403: Überprüfen Sie Ihr Auth-Token oder Ihren API-Key. Bei 404: Überprüfen Sie den URL-Pfad. Bei 500: Das Problem liegt serverseitig.

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

Fehler 28: Zeitüberschreitung der Operation

Bedeutung: Ihr Terminal zeigt curl: (28) Operation timed out oder curl: (28) Connection timed out an. Die Operation dauerte länger als die erlaubte Zeit. Dies ist der häufigste curl-Fehler — er kann während der DNS-Auflösung, der TCP-Verbindung, des SSL-Handshakes oder der Datenübertragung auftreten.
Ursachen: Typische Ursachen sind: ein langsamer oder überlasteter Server, der nicht rechtzeitig antwortet, Netzwerküberlastung oder Paketverlust, eine Firewall, die Pakete lautlos verwirft (keine Ablehnung, nur Stille), zu strenge Timeout-Werte, die mit --connect-timeout oder --max-time festgelegt wurden, oder eine Proxy-Fehlkonfiguration, die Verzögerungen verursacht.
Lösung: Erhöhen Sie das Timeout: curl --connect-timeout 30 --max-time 120 URL. Verwenden Sie den Verbose-Modus, um zu sehen, wo es hängt: curl -v URL. Testen Sie die Netzwerklatenz: ping api.example.com und traceroute api.example.com. Wenn Sie sich hinter einem Proxy befinden, versuchen Sie, diesen zu umgehen: curl --noproxy '*' URL. Bei großen Dateiübertragungen sollten Sie --retry 3 mit --retry-delay 5 verwenden.

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

Fehler 35: SSL-Verbindungsfehler

Bedeutung: Ihr Terminal zeigt curl: (35) SSL connect error an. Der SSL/TLS-Handshake ist fehlgeschlagen — curl konnte keine sichere Verbindung zum Server herstellen.
Ursachen: Häufige Ursachen: TLS-Versionskonflikt (Server erfordert TLS 1.3, aber Ihr curl unterstützt nur bis zu TLS 1.2), Inkompatibilität der Cipher-Suites, SSL-Fehlkonfiguration des Servers (abgelaufenes Zertifikat beim Handshake, unvollständige Kette), der Server unterstützt HTTPS auf dem angegebenen Port nicht oder ein Proxy oder eine Firewall fängt die SSL-Verbindung ab (MITM).
Lösung: Erzwingen Sie eine bestimmte TLS-Version: curl --tlsv1.2 URL oder curl --tlsv1.3 URL. Überprüfen Sie, was der Server unterstützt: openssl s_client -connect api.example.com:443. Aktualisieren Sie curl und OpenSSL auf die neuesten Versionen. Wenn der Server ein selbstsigniertes Zertifikat verwendet, ist dies normalerweise Fehler 60 — Fehler 35 weist typischerweise auf einen Handshake-Fehler auf Protokollebene hin.

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

Fehler 56: Empfangsfehler — Verbindung wurde zurückgesetzt

Bedeutung: Ihr Terminal zeigt curl: (56) Recv failure: Connection reset by peer an. Die Verbindung wurde erfolgreich hergestellt, aber der Datenempfang schlug fehl — der Server hat die Verbindung während der Übertragung unerwartet geschlossen oder zurückgesetzt.
Ursachen: Dies passiert oft, wenn: der Server mitten in der Übertragung abstürzt oder neu startet, ein Load Balancer oder Proxy die Verbindung trennt (Idle-Timeout, Anfrage zu groß), eine Firewall langlebige Verbindungen beendet, der Server ein Keep-Alive-Timeout hat, das kürzer als erwartet ist, oder eine Netzwerkstörung zwischen Client und Server vorliegt.
Lösung: Versuchen Sie die Anfrage erneut — vorübergehende Netzwerkprobleme sind die häufigste Ursache. Verwenden Sie den Verbose-Modus: curl -v URL, um den genauen Zeitpunkt des Fehlers zu sehen. Wenn der Fehler bei großen Uploads auftritt, versuchen Sie es mit Chunked-Transfer: curl -H "Transfer-Encoding: chunked" URL. Bei Git-Operationen, die RPC failed; curl 56 zeigen, erhöhen Sie den Puffer: git config http.postBuffer 524288000.

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

Fehler 60: SSL-Zertifikatsproblem

Bedeutung: Ihr Terminal zeigt curl: (60) SSL certificate problem: unable to get local issuer certificate an. curl konnte das SSL-Zertifikat des Servers nicht anhand seines CA-Bundles (Certificate Authority) verifizieren. Der TLS-Handshake wurde auf Protokollebene abgeschlossen, aber die Zertifikatsvalidierung schlug fehl.
Ursachen: Häufigste Ursachen: Der Server verwendet ein selbstsigniertes Zertifikat, das Zertifikat ist abgelaufen, die Zertifikatskette ist unvollständig (fehlende Zwischenzertifikate), das CA-Bundle von curl ist veraltet (häufig auf älteren Systemen oder in Docker-Containern) oder der Common Name / SAN des Zertifikats stimmt nicht mit dem angeforderten Hostnamen überein.
Lösung: Aktualisieren Sie das CA-Bundle: curl --cacert /path/to/cacert.pem URL. Laden Sie ein aktualisiertes Bundle von https://curl.se/ca/cacert.pem herunter. Zur Diagnose: openssl s_client -connect api.example.com:443 -showcerts. Für selbstsignierte Zertifikate in der Entwicklung verwenden Sie curl -k URL (niemals in der Produktion — dies deaktiviert jegliche Zertifikatsprüfung). Installieren Sie in Docker das Paket ca-certificates.

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

Andere Fehlercodes

Exit-Code	Fehlername	Beschreibung
0	CURLE_OK	Erfolg. Die Operation wurde ohne Fehler abgeschlossen.
1	CURLE_UNSUPPORTED_PROTOCOL	Nicht unterstütztes Protokoll. Die URL verwendet ein Protokoll, für das curl keine Unterstützung bietet.
3	CURLE_URL_MALFORMAT	Fehlerhafte URL. Die URL-Syntax ist ungültig oder konnte nicht analysiert werden.
5	CURLE_COULDNT_RESOLVE_PROXY	Proxy konnte nicht aufgelöst werden. Der angegebene Proxy-Hostname konnte nicht aufgelöst werden.
18	CURLE_PARTIAL_FILE	Teilweise Datei. Die Übertragung wurde unterbrochen und nur ein Teil der Datei wurde empfangen.
23	CURLE_WRITE_ERROR	Schreibfehler. curl konnte die empfangenen Daten nicht auf die Festplatte schreiben (Zugriff verweigert oder Festplatte voll).
37	CURLE_FILE_COULDNT_READ_FILE	Datei konnte nicht gelesen werden. Eine in der Anfrage referenzierte lokale Datei konnte nicht geöffnet oder gelesen werden.
52	CURLE_GOT_NOTHING	Leere Antwort vom Server. Der Server hat die Verbindung geschlossen, ohne Daten zu senden.
77	CURLE_SSL_CACERT_BADFILE	SSL-CA-Zertifikatsproblem. Die angegebene CA-Zertifikatsdatei konnte nicht gelesen oder analysiert werden.
92	CURLE_HTTP2_STREAM	HTTP/2-Stream-Fehler. Während der Übertragung ist ein Fehler auf HTTP/2-Protokollebene im Stream aufgetreten.

0CURLE_OK

Erfolg. Die Operation wurde ohne Fehler abgeschlossen.

1CURLE_UNSUPPORTED_PROTOCOL

Nicht unterstütztes Protokoll. Die URL verwendet ein Protokoll, für das curl keine Unterstützung bietet.

3CURLE_URL_MALFORMAT

Fehlerhafte URL. Die URL-Syntax ist ungültig oder konnte nicht analysiert werden.

5CURLE_COULDNT_RESOLVE_PROXY

Proxy konnte nicht aufgelöst werden. Der angegebene Proxy-Hostname konnte nicht aufgelöst werden.

18CURLE_PARTIAL_FILE

Teilweise Datei. Die Übertragung wurde unterbrochen und nur ein Teil der Datei wurde empfangen.

23CURLE_WRITE_ERROR

Schreibfehler. curl konnte die empfangenen Daten nicht auf die Festplatte schreiben (Zugriff verweigert oder Festplatte voll).

37CURLE_FILE_COULDNT_READ_FILE

Datei konnte nicht gelesen werden. Eine in der Anfrage referenzierte lokale Datei konnte nicht geöffnet oder gelesen werden.

52CURLE_GOT_NOTHING

Leere Antwort vom Server. Der Server hat die Verbindung geschlossen, ohne Daten zu senden.

77CURLE_SSL_CACERT_BADFILE

SSL-CA-Zertifikatsproblem. Die angegebene CA-Zertifikatsdatei konnte nicht gelesen oder analysiert werden.

92CURLE_HTTP2_STREAM

HTTP/2-Stream-Fehler. Während der Übertragung ist ein Fehler auf HTTP/2-Protokollebene im Stream aufgetreten.

Fehlerbehebung bei curl-Fehlern

Wenn curl fehlschlägt, helfen diese drei Flags dabei, die Ursache schnell zu identifizieren – von der DNS-Auflösung über den SSL-Handshake bis hin zum Response-Payload.

1
Ausführliche Ausgabe aktivieren
Führen Sie curl -v URL aus, um den vollständigen Request/Response-Zyklus zu sehen: DNS-Auflösung, TCP-Verbindung, TLS-Handshake, gesendete Request-Header und empfangene Response-Header. Dies ist das nützlichste Debugging-Flag.
2
HTTP-Statuscode prüfen
Führen Sie curl -o /dev/null -s -w "%{http_code}" URL aus, um nur den HTTP-Statuscode (200, 404, 500 usw.) ohne den Response-Body zu erhalten. Nützlich für schnelle Health-Checks und Skripte.
3
Fehler lautlos anzeigen
Führen Sie curl -sS URL aus, um den Fortschrittsbalken zu unterdrücken (-s), aber dennoch Fehler anzuzeigen (-S). Ideal für Skripte, bei denen Sie eine saubere Ausgabe wünschen, aber Fehler abfangen müssen.

Häufig gestellte Fragen (FAQ)

Wie überprüfe ich den curl-Exit-Code?

Nach der Ausführung eines curl-Befehls wird der Exit-Code in einer speziellen Variablen der Shell gespeichert. In Bash/Zsh führen Sie echo $? unmittelbar nach dem curl-Befehl aus. In PowerShell verwenden Sie $LASTEXITCODE. In Skripten können Sie ihn mit einer Bedingung prüfen: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. Der Exit-Code 0 bedeutet Erfolg; jede andere Zahl weist auf einen Fehler hin. Um sowohl den HTTP-Statuscode als auch den curl-Exit-Code zu sehen, kombinieren Sie curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?". Beachten Sie, dass der Exit-Code von curl sich vom HTTP-Statuscode unterscheidet – curl gibt auch bei einem HTTP 404 den Wert 0 zurück, es sei denn, Sie verwenden das Flag --fail.

Wie behebe ich den curl-Fehler 28 (Operation timed out)?

Fehler 28 bedeutet, dass die Anfrage die maximal zulässige Zeit überschritten hat. Zuerst sollten Sie den Timeout erhöhen: curl --connect-timeout 30 --max-time 120 URL. --connect-timeout begrenzt die TCP-Verbindungsphase, während --max-time die gesamte Operation begrenzt. Als Nächstes diagnostizieren Sie den Engpass mit curl -v URL – die ausführliche Ausgabe zeigt genau, wo curl stecken bleibt (DNS, Verbindung, TLS oder Transfer). Häufige Lösungen: Überprüfen Sie Ihre Netzwerkverbindung und DNS-Einstellungen, vergewissern Sie sich, dass der Server antwortet (ping und telnet), umgehen Sie Proxys mit --noproxy '*' und fügen Sie für große Downloads --retry 3 --retry-delay 5 für automatische Wiederholungsversuche hinzu.

Wie behebe ich curl-SSL-Zertifikatsfehler (Fehler 60)?

Fehler 60 bedeutet, dass curl das SSL-Zertifikat des Servers nicht verifizieren kann. Die Lösung hängt von der Ursache ab. Bei einem veralteten CA-Bundle: Laden Sie ein aktuelles von https://curl.se/ca/cacert.pem herunter und verwenden Sie curl --cacert /path/to/cacert.pem URL. Für Docker-Container: Installieren Sie das Paket ca-certificates (apt-get install ca-certificates). Für selbstsignierte Zertifikate in der Entwicklung: Verwenden Sie curl -k URL, um die Verifizierung zu überspringen – aber verwenden Sie -k niemals in der Produktion, da dies jegliche Zertifikatsprüfung deaktiviert. Zur Diagnose: Führen Sie openssl s_client -connect host:443 -showcerts aus, um die Zertifikatskette zu inspizieren. Wenn das Zertifikat abgelaufen ist oder der Hostname nicht übereinstimmt, liegt das Problem auf der Serverseite.

Was bedeutet der curl-Fehler 7 (Failed to connect)?

Fehler 7 bedeutet, dass curl den Hostnamen in eine IP-Adresse aufgelöst hat, aber keine TCP-Verbindung herstellen konnte. Der Server hat die Verbindung aktiv abgelehnt oder der Verbindungsversuch ist auf Netzwerkebene in einen Timeout gelaufen. Häufige Ursachen: Der Dienst läuft nicht auf dem Zielhost (prüfen Sie dies mit systemctl status oder docker ps), eine Firewall blockiert den Port (testen Sie dies mit telnet host port), Sie verwenden den falschen Port (z. B. 80 statt 443 oder 8080 für einen Dev-Server) oder der Listen-Backlog des Servers ist unter hoher Last voll. Zum Debuggen: Verwenden Sie curl -v URL und suchen Sie in der Ausgabe nach „Connected to“ oder „Connection refused“.