curl-Exit-Codes & Return-Codes (1-99): Referenz mit Lösung

Referenz für curl-Exit-Codes und Return-Codes (1-99): Code nachschlagen, z. B. 22, 3, 28 oder 52, und Bedeutung, häufige Ursachen sowie die genaue Lösung finden. Schnelle Alternative zur offiziellen Doku für CI/CD, Cron-Jobs und Shell-Skripte.

Zuletzt aktualisiert: 2026-09-03

Referenztabelle der curl-Exit-Codes

Code	Konstantenname	Bedeutung	Häufige Ursachen
Verbindungs-/Initialisierungsfehler
1	CURLE_UNSUPPORTED_PROTOCOL	Zeigt an, dass curl das in der URL angegebene Protokoll nicht unterstützt.	Tritt auf, wenn eine curl-Binärdatei verwendet wird, in der dieses Protokoll (z. B. gopher, ldap) beim Build deaktiviert wurde, oder bei einem Tippfehler im URL-Schema.
2	CURLE_FAILED_INIT	Zeigt an, dass die interne Initialisierung von curl fehlgeschlagen ist.	Ein seltener Initialisierungsfehler auf niedriger Ebene, meist verursacht durch Speichermangel oder eine anomale Umgebung.
3	CURLE_URL_MALFORMAT	Zeigt an, dass die angegebene URL fehlerhaft ist und von curl nicht interpretiert werden kann.	Tritt auf, wenn der URL das Schema fehlt (z. B. http://) oder sie ungültige Zeichen enthält.
5	CURLE_COULDNT_RESOLVE_PROXY	Zeigt an, dass curl den Hostnamen des angegebenen Proxy-Servers nicht auflösen konnte.	Verursacht durch einen Tippfehler im mit --proxy angegebenen Hostnamen oder einen DNS-Fehler speziell des Proxys.
6	CURLE_COULDNT_RESOLVE_HOST	Zeigt an, dass curl den Hostnamen des Zielservers nicht (per DNS) auflösen konnte.	Meist verursacht durch einen Tippfehler im Domainnamen, einen Ausfall des DNS-Servers oder die Ausführung in einer Offline-Umgebung.
7	CURLE_COULDNT_CONNECT	Zeigt an, dass der Hostname zwar aufgelöst wurde, curl aber keine TCP-Verbindung zum Server herstellen konnte.	Tritt durch eine falsche Portnummer, eine Blockierung durch eine Firewall oder einen ausgefallenen Server auf.
8	CURLE_WEIRD_SERVER_REPLY	Zeigt an, dass curl vom Server eine unerwartete Antwort erhielt, die nicht interpretiert werden konnte.	Häufig, wenn ein FTP-Server eine nicht standardkonforme Antwort zurückgibt, oder wenn curl versehentlich mit einem Server verbunden wird, der ein anderes Protokoll spricht.
9	CURLE_REMOTE_ACCESS_DENIED	Zeigt an, dass curl eine Verbindung zum Server herstellen konnte, der Zugriff jedoch verweigert wurde.	Tritt bei unzureichenden Berechtigungen für ein FTP-Verzeichnis oder bei einer serverseitigen IP-Beschränkung auf.
Datenübertragungsfehler
18	CURLE_PARTIAL_FILE	Zeigt an, dass die Übertragung vor Abschluss unterbrochen wurde und nur ein Teil der Datei empfangen werden konnte.	Tritt durch eine kurze Netzwerkunterbrechung auf, oder wenn der Server die Verbindung schließt, bevor die angekündigte Content-Length erreicht wurde.
23	CURLE_WRITE_ERROR	Zeigt an, dass das Schreiben von Daten auf die lokale Festplatte oder an das Callback-Ziel fehlgeschlagen ist.	Tritt auf, wenn der Speicherplatz voll ist oder curl keine Schreibberechtigung für die Ausgabedatei hat.
26	CURLE_READ_ERROR	Zeigt an, dass das Lesen der hochzuladenden lokalen Datei fehlgeschlagen ist.	Tritt auf, wenn die mit -T/--upload-file angegebene Datei nicht existiert oder curl keine Leseberechtigung dafür hat.
52	CURLE_GOT_NOTHING	Zeigt an, dass curl eine Verbindung zum Server herstellen konnte, aber überhaupt keine Antwort erhielt.	Meist verursacht durch einen Absturz des Serverprozesses mitten in der Anfrage, oder eine Fehlkonfiguration, die eine leere Antwort zurückgibt.
55	CURLE_SEND_ERROR	Zeigt an, dass das Senden von Daten über das Netzwerk fehlgeschlagen ist.	Tritt auf, wenn die Gegenseite die Verbindung sofort nach dem Aufbau trennt, oder aufgrund eines Problems mit der lokalen Netzwerkschnittstelle.
56	CURLE_RECV_ERROR	Zeigt an, dass der Empfang von Daten aus dem Netzwerk fehlgeschlagen ist.	Häufig zu beobachten, wenn die Gegenseite die Verbindung während der Übertragung unerwartet zurücksetzt (Connection reset by peer).
63	CURLE_FILESIZE_EXCEEDED	Zeigt an, dass die Dateigröße das mit --max-filesize festgelegte Limit überschritten hat.	Tritt auf, wenn die Antwort größer ausfällt als erwartet und das aus Sicherheitsgründen konfigurierte Limit erreicht.
78	CURLE_REMOTE_FILE_NOT_FOUND	Zeigt an, dass die angegebene Datei auf dem entfernten Server nicht existiert (z. B. bei FTP).	Tritt durch einen Tippfehler im FTP-Pfad auf, oder wenn die Zieldatei bereits gelöscht oder verschoben wurde.
SSL/TLS-Zertifikatsfehler
35	CURLE_SSL_CONNECT_ERROR	Zeigt an, dass während des SSL/TLS-Handshakes ein Problem aufgetreten ist, sodass die Verbindung nicht hergestellt werden konnte.	Häufig verursacht durch eine Diskrepanz zwischen den vom Server und vom Client unterstützten TLS-Versionen oder Cipher-Suites.
51	CURLE_PEER_FAILED_VERIFICATION	Zeigt an, dass die Überprüfung des Serverzertifikats fehlgeschlagen ist (z. B. stimmt der Zertifikatsinhalt nicht mit dem Hostnamen überein).	Tritt beim Zugriff auf ein selbstsigniertes Zertifikat auf, oder wenn der Common Name/SAN des Zertifikats vom Zielhostnamen abweicht.
58	CURLE_SSL_CERTPROBLEM	Zeigt ein Problem mit dem lokal angegebenen Client-Zertifikat an.	Meist verursacht durch ein ungültiges Format der mit --cert angegebenen Zertifikatsdatei oder eine falsch eingegebene Passphrase.
60	CURLE_SSL_CACERT	Zeigt an, dass die CA-Zertifikatskette zur Überprüfung des Serverzertifikats nicht bestätigt werden konnte.	Tritt auf, wenn das CA-Zertifikatspaket veraltet ist, oder eine selbstsignierte CA (etwa eines internen Proxys) nicht im Trust Store registriert ist. -k/--insecure ist ein Workaround, wird für den Produktionseinsatz jedoch nicht empfohlen.
HTTP-/Authentifizierungsfehler
22	CURLE_HTTP_RETURNED_ERROR	Zeigt an, dass bei angegebener Option -f/--fail die HTTP-Antwort einen Fehlerstatus von 400 oder höher zurückgegeben hat.	Wird absichtlich in CI/CD-Skripten ausgelöst, die curl -f verwenden, um einen API-Fehlerstatus als Fehlschlag zu erkennen.
67	CURLE_LOGIN_DENIED	Zeigt an, dass der Login (die Authentifizierung) beim Server abgelehnt wurde.	Meist verursacht durch einen falschen Benutzernamen oder ein falsches Passwort, oder eine Kontosperrung bei Protokollen wie FTP/SMTP.
Sonstige
27	CURLE_OUT_OF_MEMORY	Zeigt an, dass die Speicherzuweisung während der Ausführung von curl fehlgeschlagen ist.	Eine seltene Situation, etwa der Versuch, eine sehr große Datei auf einem speicherbegrenzten System zu verarbeiten.
28	CURLE_OPERATION_TIMEDOUT	Zeigt an, dass der Vorgang nicht innerhalb der mit --connect-timeout/--max-time usw. festgelegten Zeitgrenze abgeschlossen wurde.	Einer der häufigsten Fehler in CI, verursacht durch eine langsame Serverantwort, Netzwerklatenz oder einen zu kurz eingestellten Timeout-Wert.
47	CURLE_TOO_MANY_REDIRECTS	Zeigt an, dass die Anzahl der Weiterleitungen das mit --max-redirs festgelegte Limit überschritten hat.	Tritt bei einer Weiterleitungsschleife (301/302, die sich zirkulär weiterleiten) oder einer legitimen Weiterleitungskette auf, die länger ist als das Standardlimit (50).

Was ist ein curl-Exit-Code?

Ein curl-Exit-Code ist die Zahl, die curl nach Abschluss der Ausführung an die Shell zurückgibt (abrufbar über $?). Sie zeigt an, ob die Anfrage erfolgreich war und, falls nicht, warum. Anders als der HTTP-Statuscode, den der Server zurückgibt, beschreibt der Exit-Code das Ergebnis des curl-Befehls selbst — etwa einen DNS-Fehler, einen Verbindungs-Timeout oder einen SSL-Handshake-Fehler.

Mit diesem Tool können Sie jeden Exit-Code (1-99) nachschlagen und erhalten Bedeutung sowie häufige Ursachen, oder die vollständige Referenztabelle nach Code, Konstantenname oder Stichwort filtern. Es richtet sich an alle, die Fehlschläge von curl in CI/CD-Pipelines, Cron-Jobs oder Shell-Skripten debuggen müssen, etwa beim Aufruf von APIs oder beim Herunterladen von Dateien.

So verwenden Sie das Tool

Exit-Code-Nummer eingeben Geben Sie die Zahl, die Sie nach einem fehlgeschlagenen curl-Befehl mit echo $? ermittelt haben, in das Suchfeld ein.
Bedeutung und häufige Ursachen ansehen Das Tool zeigt an, was der Code bedeutet und in welchen Situationen er typischerweise auftritt.
In der Referenztabelle filtern Wenn Sie die genaue Nummer nicht kennen, filtern Sie die Tabelle stattdessen nach einem Stichwort.
Lösungsvorschlag prüfen Nutzen Sie die häufigen Ursachen als Ausgangspunkt, um die passende Korrektur in Ihrem Skript oder Ihrer Umgebung vorzunehmen.

Tipps für die Nutzung

Den Exit Code können Sie direkt danach mit $? (Bash) oder %errorlevel% (Windows) prüfen. In Shell-Skripten ist eine Verzweigung wie curl ... || echo "failed with $?" ein praktisches Muster.
28 (Timeout) und 7 (Verbindungsfehler) werden oft verwechselt: 28 tritt auf, wenn die Antwort nach dem Verbindungsaufbau langsam kommt, während 7 auftritt, wenn die TCP-Verbindung selbst gar nicht erst zustande kommt.
Wenn 60 (CA-Zertifikatsfehler) auftritt, sollten Sie es nicht einfach mit -k/--insecure umgehen — prüfen Sie zunächst, ob Ihr CA-Zertifikatspaket (ca-certificates) aktuell ist. Der routinemäßige Einsatz von -k in Produktionsumgebungen erhöht das Risiko von Man-in-the-Middle-Angriffen.
22 (HTTP-Fehler) tritt nur auf, wenn Sie die Option -f/--fail hinzufügen. Ohne diese liefert curl auch bei einer 404- oder 500-Antwort den Exit Code 0 (Erfolg) zurück — fügen Sie -f daher immer hinzu, wenn CI Fehler erkennen soll.

Anwendungsfälle

Fehlersuche in einer CI/CD-Pipeline

Ermitteln Sie schnell, warum ein curl-basierter Deploy- oder Health-Check-Schritt fehlgeschlagen ist, indem Sie den Exit-Code aus dem Build-Log nachschlagen.

Diagnose eines stillschweigend fehlschlagenden Cron-Jobs

Cron-Jobs zeigen selten eine Ausgabe an, daher ist die Prüfung des protokollierten Exit-Codes oft der schnellste Weg zur Ursache.

Robuste Fehlerbehandlung in Shell-Skripten schreiben

Schlagen Sie nach, welche Codes ein wiederholbares Netzwerkproblem und welche einen dauerhaften Fehler anzeigen, um die Skriptlogik entsprechend zu verzweigen.

Postmortem nach einem Vorfall

Bestätigen Sie beim Auswerten der Logs nach einem Ausfall genau, welche Fehlerklasse (DNS, TLS, Timeout) vorlag.

curl und Netzwerkgrundlagen lernen

Nutzen Sie die Tabelle, um systematisch zu verstehen, welche Phase einer Übertragung (Auflösung, Verbindung, TLS, Transfer) jeweils fehlschlagen kann.

Glossar

Exit Code: Die Zahl, die ein Programm beim Beenden an die Shell zurückgibt. 0 bedeutet Erfolg; curl verwendet 1-99, um bestimmte Fehlertypen anzuzeigen.
CURLcode: Das interne Enum in libcurl, das jeden Fehlertyp definiert. Die Exit-Codes der Kommandozeile bilden sich direkt auf dieses Enum ab.
libcurl: Die C-Bibliothek, die die Kernübertragungslogik von curl implementiert. Das Kommandozeilen-Tool curl ist nur ein schlanker Wrapper darum.
--fail / -f-Option: Eine curl-Option, die dafür sorgt, dass HTTP-Fehlerantworten (400 und höher) den Exit-Code 22 statt des Standard-Exit-Codes 0 erzeugen.
Timeout vs. Verbindung verweigert: Timeout (28) bedeutet, dass keine Antwort rechtzeitig ankam; verweigert/fehlgeschlagen (7) bedeutet, dass die TCP-Verbindung selbst nicht aufgebaut werden konnte.
DNS-Auflösung: Der Vorgang, bei dem ein Hostname in eine IP-Adresse umgewandelt wird. Schlägt dies fehl, gibt curl den Exit-Code 6 zurück.
SSL/TLS-Handshake: Der Aushandlungsprozess, mit dem Client und Server eine verschlüsselte Verbindung aufbauen. Probleme dabei führen typischerweise zu Exit-Code 35, 51, 58 oder 60.

FAQ

Direkt nach der Ausführung des curl-Befehls können Sie ihn mit echo $? in Bash/Zsh, echo %errorlevel% in der Windows-Eingabeaufforderung oder $LASTEXITCODE in PowerShell prüfen.

Überprüfen Sie zunächst die Einstellungen von --connect-timeout und --max-time und verlängern Sie diese bei Bedarf. Wenn der Server dauerhaft langsam antwortet, prüfen Sie auch die Serverlast und den Netzwerkpfad (Proxy, VPN usw.).

Nein, es handelt sich um unterschiedliche Dinge. HTTP-Statuscodes (z. B. 404 oder 500) sind Antworten auf Protokollebene, die vom Server zurückgegeben werden, während curl-Exit-Codes das Ergebnis der Ausführung des curl-Befehls selbst anzeigen (Verbindungsfehler, Timeout usw.). Da curl HTTP-Fehler standardmäßig als Exit Code 0 (Erfolg) behandelt, sollten Sie beide nicht verwechseln.

Fügen Sie die Option curl -f (--fail) hinzu, damit curl den Exit Code 22 zurückgibt, sobald die HTTP-Antwort 400 oder höher ist. Ohne diese Option führt das erfolgreiche Abrufen einer Fehlerseite weiterhin zu Exit Code 0.

6 (COULDNT_RESOLVE_HOST) ist ein Fehler in der DNS-Phase, bei dem der Hostname nicht in eine IP-Adresse aufgelöst werden konnte. 7 (COULDNT_CONNECT) ist ein Fehler, bei dem die Namensauflösung erfolgreich war, aber die TCP-Verbindung zu dieser IP-Adresse nicht hergestellt werden konnte.

Übrigens – Das Exit-Code-System von curl

curl ist ein Kommandozeilen-Tool, dessen Entwicklung 1996 von Daniel Stenberg begonnen wurde, ursprünglich unter dem Namen „httpget“. Heute ist curl standardmäßig auf praktisch jeder Linux-Distribution, macOS sowie Windows 10 und neuer vorinstalliert und gehört damit zu den grundlegendsten Werkzeugen für Webentwickler.

Das Exit-Code-System entspricht direkt dem internen Fehler-Enum von libcurl, CURLcode, und ist als fortlaufende Nummerierung ab `CURLE_OK` (Erfolg, Exit Code 0) definiert. Lücken in der Nummerierung entstehen dadurch, dass im Laufe der Entwicklung einige Fehlercodes als veraltet markiert oder zusammengeführt wurden.

Interessanterweise bilden die Exit Codes von curl ein eigenständiges System, das unabhängig von der allgemeinen POSIX-Konvention (0 = Erfolg, 1 = allgemeiner Fehler) ist. Das bedeutet: Wer in einem Shell-Skript die Exit Codes mehrerer Tools gemeinsam verarbeiten möchte, muss die Bedeutung in jedem einzelnen Handbuch nachschlagen.

Alle Wissenstexte ansehen