curl-foutcodes: complete referentie

Wanneer een curl-commando mislukt, retourneert het een numerieke exitcode (ook wel curl-foutcode genoemd) die het type fout identificeert. Je kunt de curl-exitcode controleren door echo $? direct na het curl-commando uit te voeren (of $LASTEXITCODE in PowerShell). Exitcode 0 betekent succes; elk ander nummer duidt op een specifiek probleem — van DNS-resolutiefouten en verbindingstimeouts tot SSL-certificaatproblemen. Deze pagina is een volledige referentie van de meest voorkomende curl-foutcodes met uitleg, oorzaken en oplossingen. Als je met curl-commando's in je code werkt, plak ze in curl2code om ze te converteren naar de programmeertaal van je keuze.

Snelle referentietabel

Exitcode	Foutnaam	Beschrijving
0	CURLE_OK	Succes. De bewerking is zonder fouten voltooid.
1	CURLE_UNSUPPORTED_PROTOCOL	Niet-ondersteund protocol. De URL gebruikt een protocol waarvoor curl niet is gebouwd.
3	CURLE_URL_MALFORMAT	Ongeldige URL. De URL-syntaxis is ongeldig of kon niet worden geparseerd.
5	CURLE_COULDNT_RESOLVE_PROXY	Kon proxy niet resolven. De opgegeven proxy-hostname kon niet worden geresolveerd.
6	CURLE_COULDNT_RESOLVE_HOST	DNS-lookup mislukt — de hostnaam kon niet worden geresolveerd naar een IP-adres.
7	CURLE_COULDNT_CONNECT	TCP-verbinding mislukt — server is uitgeschakeld, poort is geblokkeerd of firewall weigert verbindingen.
18	CURLE_PARTIAL_FILE	Onvolledig bestand. De overdracht werd onderbroken en slechts een deel van het bestand werd ontvangen.
22	CURLE_HTTP_RETURNED_ERROR	Server retourneerde een HTTP-fout (4xx/5xx) en de --fail-vlag werd gebruikt.
23	CURLE_WRITE_ERROR	Schrijffout. curl kon de ontvangen data niet naar schijf schrijven (toestemming geweigerd of schijf vol).
28	CURLE_OPERATION_TIMEDOUT	De bewerking overschreed de maximaal toegestane tijd (DNS, verbinding of overdracht).
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS-handshake mislukt — protocolversie- of cipher suite-mismatch.
37	CURLE_FILE_COULDNT_READ_FILE	Kon bestand niet lezen. Een lokaal bestand waarnaar in het verzoek wordt verwezen, kon niet worden geopend of gelezen.
52	CURLE_GOT_NOTHING	Leeg antwoord van server. De server sloot de verbinding zonder data te versturen.
56	CURLE_RECV_ERROR	Verbinding gereset — de server verbrak de verbinding tijdens gegevensoverdracht.
60	CURLE_SSL_CACERT	SSL-certificaatverificatie mislukt — verlopen, zelfondertekend of CA-bundel is verouderd.
77	CURLE_SSL_CACERT_BADFILE	SSL CA-certificaatprobleem. Kon het opgegeven CA-certificaatbestand niet lezen of parseren.
92	CURLE_HTTP2_STREAM	HTTP/2-streamfout. Er is een HTTP/2-protocol-niveau streamfout opgetreden tijdens de overdracht.

0CURLE_OK

Succes. De bewerking is zonder fouten voltooid.

1CURLE_UNSUPPORTED_PROTOCOL

Niet-ondersteund protocol. De URL gebruikt een protocol waarvoor curl niet is gebouwd.

3CURLE_URL_MALFORMAT

Ongeldige URL. De URL-syntaxis is ongeldig of kon niet worden geparseerd.

5CURLE_COULDNT_RESOLVE_PROXY

Kon proxy niet resolven. De opgegeven proxy-hostname kon niet worden geresolveerd.

6CURLE_COULDNT_RESOLVE_HOST

DNS-lookup mislukt — de hostnaam kon niet worden geresolveerd naar een IP-adres.

7CURLE_COULDNT_CONNECT

TCP-verbinding mislukt — server is uitgeschakeld, poort is geblokkeerd of firewall weigert verbindingen.

18CURLE_PARTIAL_FILE

Onvolledig bestand. De overdracht werd onderbroken en slechts een deel van het bestand werd ontvangen.

22CURLE_HTTP_RETURNED_ERROR

Server retourneerde een HTTP-fout (4xx/5xx) en de --fail-vlag werd gebruikt.

23CURLE_WRITE_ERROR

Schrijffout. curl kon de ontvangen data niet naar schijf schrijven (toestemming geweigerd of schijf vol).

28CURLE_OPERATION_TIMEDOUT

De bewerking overschreed de maximaal toegestane tijd (DNS, verbinding of overdracht).

35CURLE_SSL_CONNECT_ERROR

SSL/TLS-handshake mislukt — protocolversie- of cipher suite-mismatch.

37CURLE_FILE_COULDNT_READ_FILE

Kon bestand niet lezen. Een lokaal bestand waarnaar in het verzoek wordt verwezen, kon niet worden geopend of gelezen.

52CURLE_GOT_NOTHING

Leeg antwoord van server. De server sloot de verbinding zonder data te versturen.

56CURLE_RECV_ERROR

Verbinding gereset — de server verbrak de verbinding tijdens gegevensoverdracht.

60CURLE_SSL_CACERT

SSL-certificaatverificatie mislukt — verlopen, zelfondertekend of CA-bundel is verouderd.

77CURLE_SSL_CACERT_BADFILE

SSL CA-certificaatprobleem. Kon het opgegeven CA-certificaatbestand niet lezen of parseren.

92CURLE_HTTP2_STREAM

HTTP/2-streamfout. Er is een HTTP/2-protocol-niveau streamfout opgetreden tijdens de overdracht.

Fout 6: kon host niet resolven

Wat het betekent: Je terminal toont curl: (6) Could not resolve host. curl kon de hostnaam niet resolven naar een IP-adres — de DNS-lookup mislukte voordat er een verbinding werd geprobeerd.
Oorzaken: De meest voorkomende oorzaken zijn: een typefout in de hostnaam (bijv. curl https://apiexample.com in plaats van api.example.com), DNS-serverproblemen (je geconfigureerde DNS is onbereikbaar), geen netwerkverbinding (Wi-Fi niet verbonden, VPN niet verbonden), of het domein bestaat werkelijk niet.
Hoe op te lossen: Controleer eerst of de URL correct is. Test vervolgens de DNS-resolutie direct: nslookup api.example.com of dig api.example.com. Als DNS mislukt, probeer een andere DNS-server: curl --dns-servers 8.8.8.8 https://api.example.com. Controleer je /etc/resolv.conf of netwerkinstellingen. Als je achter een bedrijfs-VPN zit, zorg ervoor dat de interne DNS de host kan resolven.

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

Fout 7: verbinding mislukt

Wat het betekent: Je terminal toont curl: (7) Failed to connect to host port: Connection refused. curl heeft de hostnaam geresolveerd maar kon geen TCP-verbinding met de server tot stand brengen — de verbinding werd actief geweigerd of er trad een timeout op op TCP-niveau.
Oorzaken: Veelvoorkomende oorzaken zijn: de server is uitgeschakeld of draait niet, een firewall blokkeert de poort (controleer zowel lokale als server-side firewalls), de poort is verkeerd (bijv. de service draait op 8080 maar je verbindt met 443), of de listen-backlog van de server is vol bij zware belasting.
Hoe op te lossen: Controleer of de server draait: ping api.example.com en telnet api.example.com 443. Controleer of de juiste poort open is: nmap -p 443 api.example.com. Schakel de lokale firewall tijdelijk uit om te testen. Als je Docker gebruikt, zorg ervoor dat de containerpoort gepubliceerd is. Probeer met verbose modus: curl -v https://api.example.com om precies te zien waar de verbinding mislukt.

$ curl https://localhost:8080/api

Fout 22: HTTP retourneerde fout

Wat het betekent: Je terminal toont curl: (22) The requested URL returned error. De server retourneerde een HTTP-foutstatuscode (4xx of 5xx) en curl werd aangeroepen met -f of --fail, wat curl vertelt om HTTP-fouten als mislukkingen te behandelen.
Oorzaken: De fout wordt veroorzaakt door HTTP-statuscodes zoals 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) of 500 (Internal Server Error) — maar alleen wanneer --fail wordt gebruikt. Zonder --fail sluit curl af met code 0, zelfs bij HTTP-fouten. Veelvoorkomende oorzaken: verkeerde URL, ontbrekende authenticatie, onvoldoende rechten of server-side bugs.
Hoe op te lossen: Voer curl uit zonder --fail om de volledige response body te zien — deze bevat vaak het daadwerkelijke foutbericht. Controleer de HTTP-statuscode: curl -w "%{http_code}" -o /dev/null -s URL. Voor 401/403: controleer je auth-token of API-sleutel. Voor 404: controleer het URL-pad nogmaals. Voor 500: het probleem is server-side.

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

Fout 28: bewerking verlopen

Wat het betekent: Je terminal toont curl: (28) Operation timed out of curl: (28) Connection timed out. De bewerking duurde langer dan de toegestane tijd. Dit is de meest voorkomende curl-fout — deze kan optreden tijdens DNS-resolutie, TCP-verbinding, SSL-handshake of gegevensoverdracht.
Oorzaken: Typische oorzaken zijn: trage of overbelaste server die niet op tijd reageert, netwerkcongestie of pakketverlies, firewall die pakketten stilletjes dropt (geen afwijzing, alleen stilte), te strikte timeout-waarden ingesteld met --connect-timeout of --max-time, of een proxy-misconfiguratie die vertragingen veroorzaakt.
Hoe op te lossen: Verhoog de timeout: curl --connect-timeout 30 --max-time 120 URL. Gebruik verbose modus om te zien waar het vastloopt: curl -v URL. Test netwerklatentie: ping api.example.com en traceroute api.example.com. Als je achter een proxy zit, probeer deze te omzeilen: curl --noproxy '*' URL. Voor grote bestandsoverdrachten overweeg het gebruik van --retry 3 met --retry-delay 5.

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

Fout 35: SSL-verbindingsfout

Wat het betekent: Je terminal toont curl: (35) SSL connect error. De SSL/TLS-handshake is mislukt — curl kon geen beveiligde verbinding met de server tot stand brengen.
Oorzaken: Veelvoorkomende oorzaken: TLS-versiemismatch (server vereist TLS 1.3 maar je curl ondersteunt alleen tot TLS 1.2), cipher suite-incompatibiliteit, SSL-misconfiguratie van de server (verlopen certificaat gepresenteerd tijdens handshake, onvolledige keten), de server ondersteunt eigenlijk geen HTTPS op de opgegeven poort, of een proxy of firewall onderschept de SSL-verbinding (MITM).
Hoe op te lossen: Forceer een specifieke TLS-versie: curl --tlsv1.2 URL of curl --tlsv1.3 URL. Controleer wat de server ondersteunt: openssl s_client -connect api.example.com:443. Werk curl en OpenSSL bij naar de nieuwste versies. Als de server een zelfondertekend certificaat gebruikt, is dit meestal fout 60 — fout 35 duidt doorgaans op een protocol-niveau handshake-fout.

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

Fout 56: ontvangstfout — verbinding gereset

Wat het betekent: Je terminal toont curl: (56) Recv failure: Connection reset by peer. De verbinding werd succesvol tot stand gebracht, maar het ontvangen van data mislukte — de server sloot of resette de verbinding onverwacht tijdens de overdracht.
Oorzaken: Dit gebeurt vaak wanneer: de server crasht of herstart tijdens de overdracht, een load balancer of proxy de verbinding verbreekt (idle timeout, verzoek te groot), een firewall langdurige verbindingen beëindigt, de server een keep-alive timeout heeft die korter is dan verwacht, of er een netwerkstoring is tussen client en server.
Hoe op te lossen: Probeer het verzoek opnieuw — tijdelijke netwerkproblemen zijn de meest voorkomende oorzaak. Gebruik verbose modus: curl -v URL om het exacte punt van falen te zien. Als de fout optreedt tijdens grote uploads, probeer chunked transfer: curl -H "Transfer-Encoding: chunked" URL. Voor Git-bewerkingen die RPC failed; curl 56 tonen, vergroot de buffer: git config http.postBuffer 524288000.

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

Fout 60: SSL-certificaatprobleem

Wat het betekent: Je terminal toont curl: (60) SSL certificate problem: unable to get local issuer certificate. curl kon het SSL-certificaat van de server niet verifiëren tegen zijn CA (Certificate Authority) bundel. De TLS-handshake werd op protocolniveau voltooid, maar de certificaatvalidatie mislukte.
Oorzaken: Meest voorkomende oorzaken: de server gebruikt een zelfondertekend certificaat, het certificaat is verlopen, de certificaatketen is onvolledig (ontbrekende tussenliggende certificaten), curl's CA-bundel is verouderd (gebruikelijk op oudere systemen of in Docker-containers), of de Common Name / SAN van het certificaat komt niet overeen met de gevraagde hostnaam.
Hoe op te lossen: Werk de CA-bundel bij: curl --cacert /path/to/cacert.pem URL. Download een bijgewerkte bundel van https://curl.se/ca/cacert.pem. Om te diagnosticeren: openssl s_client -connect api.example.com:443 -showcerts. Voor zelfondertekende certificaten in ontwikkeling, gebruik curl -k URL (nooit in productie — het schakelt alle certificaatverificatie uit). In Docker, installeer het ca-certificates-pakket.

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

Overige foutcodes

Exitcode	Foutnaam	Beschrijving
0	CURLE_OK	Succes. De bewerking is zonder fouten voltooid.
1	CURLE_UNSUPPORTED_PROTOCOL	Niet-ondersteund protocol. De URL gebruikt een protocol waarvoor curl niet is gebouwd.
3	CURLE_URL_MALFORMAT	Ongeldige URL. De URL-syntaxis is ongeldig of kon niet worden geparseerd.
5	CURLE_COULDNT_RESOLVE_PROXY	Kon proxy niet resolven. De opgegeven proxy-hostname kon niet worden geresolveerd.
18	CURLE_PARTIAL_FILE	Onvolledig bestand. De overdracht werd onderbroken en slechts een deel van het bestand werd ontvangen.
23	CURLE_WRITE_ERROR	Schrijffout. curl kon de ontvangen data niet naar schijf schrijven (toestemming geweigerd of schijf vol).
37	CURLE_FILE_COULDNT_READ_FILE	Kon bestand niet lezen. Een lokaal bestand waarnaar in het verzoek wordt verwezen, kon niet worden geopend of gelezen.
52	CURLE_GOT_NOTHING	Leeg antwoord van server. De server sloot de verbinding zonder data te versturen.
77	CURLE_SSL_CACERT_BADFILE	SSL CA-certificaatprobleem. Kon het opgegeven CA-certificaatbestand niet lezen of parseren.
92	CURLE_HTTP2_STREAM	HTTP/2-streamfout. Er is een HTTP/2-protocol-niveau streamfout opgetreden tijdens de overdracht.

0CURLE_OK

Succes. De bewerking is zonder fouten voltooid.

1CURLE_UNSUPPORTED_PROTOCOL

Niet-ondersteund protocol. De URL gebruikt een protocol waarvoor curl niet is gebouwd.

3CURLE_URL_MALFORMAT

Ongeldige URL. De URL-syntaxis is ongeldig of kon niet worden geparseerd.

5CURLE_COULDNT_RESOLVE_PROXY

Kon proxy niet resolven. De opgegeven proxy-hostname kon niet worden geresolveerd.

18CURLE_PARTIAL_FILE

Onvolledig bestand. De overdracht werd onderbroken en slechts een deel van het bestand werd ontvangen.

23CURLE_WRITE_ERROR

Schrijffout. curl kon de ontvangen data niet naar schijf schrijven (toestemming geweigerd of schijf vol).

37CURLE_FILE_COULDNT_READ_FILE

Kon bestand niet lezen. Een lokaal bestand waarnaar in het verzoek wordt verwezen, kon niet worden geopend of gelezen.

52CURLE_GOT_NOTHING

Leeg antwoord van server. De server sloot de verbinding zonder data te versturen.

77CURLE_SSL_CACERT_BADFILE

SSL CA-certificaatprobleem. Kon het opgegeven CA-certificaatbestand niet lezen of parseren.

92CURLE_HTTP2_STREAM

HTTP/2-streamfout. Er is een HTTP/2-protocol-niveau streamfout opgetreden tijdens de overdracht.

Hoe curl-fouten debuggen

Wanneer curl mislukt, helpen deze drie vlaggen je snel de oorzaak te identificeren — van DNS-resolutie tot SSL-handshake tot response-payload.

1
Schakel uitgebreide uitvoer in
Voer curl -v URL uit om de volledige verzoek-/antwoordcyclus te zien: DNS-resolutie, TCP-verbinding, TLS-handshake, verzonden verzoekheaders en ontvangen antwoordheaders. Dit is de meest nuttige debugging-vlag.
2
Controleer de HTTP-statuscode
Voer curl -o /dev/null -s -w "%{http_code}" URL uit om alleen de HTTP-statuscode (200, 404, 500, enz.) te krijgen zonder de response body. Handig voor snelle gezondheidscontroles en scripting.
3
Toon fouten stil
Voer curl -sS URL uit om de voortgangsbalk te onderdrukken (-s) maar wel fouten te tonen (-S). Perfect voor scripts waar je schone uitvoer wilt maar fouten moet opvangen.

Veelgestelde vragen

Hoe controleer je de curl-exitcode?

Na het uitvoeren van een curl-commando wordt de exitcode opgeslagen in de speciale variabele van de shell. In Bash/Zsh, voer echo $? uit direct na het curl-commando. In PowerShell, gebruik $LASTEXITCODE. In scripts kun je het controleren met een conditional: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. Exitcode 0 betekent succes; elk ander nummer duidt op een fout. Om zowel de HTTP-statuscode als de curl-exitcode te zien, combineer curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?". Let op dat curl's exitcode verschilt van de HTTP-statuscode — curl retourneert 0 zelfs voor HTTP 404, tenzij je de --fail-vlag gebruikt.

Hoe los je curl-fout 28 (bewerking verlopen) op?

Fout 28 betekent dat het verzoek de maximaal toegestane tijd heeft overschreden. Verhoog eerst de timeout: curl --connect-timeout 30 --max-time 120 URL. De --connect-timeout beperkt de TCP-verbindingsfase, terwijl --max-time de gehele bewerking beperkt. Diagnosticeer vervolgens het knelpunt met curl -v URL — de uitgebreide uitvoer toont precies waar curl vastloopt (DNS, verbinding, TLS of overdracht). Veelvoorkomende oplossingen: controleer je netwerkverbinding en DNS-instellingen, verifieer of de server reageert (ping en telnet), omzeil proxy's met --noproxy '*', en voeg voor grote downloads --retry 3 --retry-delay 5 toe voor automatische herhaalpogingen.

Hoe los je curl SSL-certificaatfouten (fout 60) op?

Fout 60 betekent dat curl het SSL-certificaat van de server niet kan verifiëren. De oplossing hangt af van de oorzaak. Voor een verouderde CA-bundel: download een nieuwe van https://curl.se/ca/cacert.pem en gebruik curl --cacert /path/to/cacert.pem URL. Voor Docker-containers: installeer het ca-certificates-pakket (apt-get install ca-certificates). Voor zelfondertekende certificaten in ontwikkeling: gebruik curl -k URL om verificatie over te slaan — maar gebruik -k nooit in productie omdat het alle certificaatcontrole uitschakelt. Om te diagnosticeren: voer openssl s_client -connect host:443 -showcerts uit om de certificaatketen te inspecteren. Als het certificaat verlopen is of de hostnaam niet overeenkomt, ligt het probleem aan de serverzijde.

Wat betekent curl-fout 7 (verbinding mislukt)?

Fout 7 betekent dat curl de hostnaam naar een IP-adres heeft geresolveerd, maar geen TCP-verbinding kon tot stand brengen. De server heeft de verbinding actief geweigerd of de verbindingspoging is verlopen op netwerkniveau. Veelvoorkomende oorzaken: de service draait niet op de doelhost (controleer met systemctl status of docker ps), een firewall blokkeert de poort (test met telnet host port), je gebruikt de verkeerde poort (bijv. 80 in plaats van 443, of 8080 voor een dev-server), of de listen-backlog van de server is vol bij zware belasting. Om te debuggen: gebruik curl -v URL en zoek naar "Connected to" of "Connection refused" in de uitvoer.