Codici di errore curl: Riferimento completo

Tabella di riferimento rapido

Errore 6: Impossibile risolvere l'host

Cosa significa

Il tuo terminale mostra curl: (6) Could not resolve host. curl non è riuscito a risolvere il nome host in un indirizzo IP — la ricerca DNS è fallita prima ancora di tentare la connessione.

Cause

Le cause più comuni sono: un errore di battitura nel nome host (ad es. curl https://apiexample.com invece di api.example.com), problemi con il server DNS (il DNS configurato non è raggiungibile), nessuna connessione di rete (Wi-Fi disconnesso, VPN non connessa), oppure il dominio non esiste realmente.

Come risolvere

Per prima cosa, verifica che l'URL sia corretto. Poi testa la risoluzione DNS direttamente: nslookup api.example.com o dig api.example.com. Se il DNS fallisce, prova un server DNS diverso: curl --dns-servers 8.8.8.8 https://api.example.com. Controlla il tuo /etc/resolv.conf o le impostazioni di rete. Se sei dietro una VPN aziendale, assicurati che il DNS interno possa risolvere l'host.

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

Errore 7: Connessione fallita

Cosa significa

Il tuo terminale mostra curl: (7) Failed to connect to host port: Connection refused. curl ha risolto il nome host ma non è riuscito a stabilire una connessione TCP con il server — la connessione è stata attivamente rifiutata o è scaduta a livello TCP.

Cause

Le cause comuni includono: il server è spento o non in esecuzione, un firewall sta bloccando la porta (controlla sia il firewall locale che quello del server), la porta è errata (ad es. il servizio gira sulla 8080 ma stai connettendo alla 443), oppure il backlog di ascolto del server è pieno a causa di un carico elevato.

Come risolvere

Verifica che il server sia in esecuzione: ping api.example.com e telnet api.example.com 443. Controlla se la porta corretta è aperta: nmap -p 443 api.example.com. Disabilita temporaneamente il firewall locale per testare. Se usi Docker, assicurati che la porta del container sia pubblicata. Prova in modalità verbosa: curl -v https://api.example.com per vedere esattamente dove la connessione fallisce.

$ curl https://localhost:8080/api

Errore 22: Errore HTTP restituito

Cosa significa

Il tuo terminale mostra curl: (22) The requested URL returned error. Il server ha restituito un codice di stato HTTP di errore (4xx o 5xx) e curl è stato invocato con -f o --fail, che indica a curl di trattare gli errori HTTP come fallimenti.

Cause

L'errore è innescato dai codici di stato HTTP come 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) o 500 (Internal Server Error) — ma solo quando viene usato --fail. Senza --fail, curl termina con codice 0 anche in caso di errori HTTP. Le cause comuni sono: URL errato, autenticazione mancante, permessi insufficienti o bug lato server.

Come risolvere

Esegui curl senza --fail per vedere il corpo completo della risposta — spesso contiene il messaggio di errore effettivo. Controlla il codice di stato HTTP: curl -w "%{http_code}" -o /dev/null -s URL. Per 401/403: verifica il tuo token di autenticazione o chiave API. Per 404: ricontrolla il percorso URL. Per 500: il problema è lato server.

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

Errore 28: Operazione scaduta

Cosa significa

Il tuo terminale mostra curl: (28) Operation timed out o curl: (28) Connection timed out. L'operazione ha impiegato più tempo di quello consentito. Questo è l'errore curl più comune — può verificarsi durante la risoluzione DNS, la connessione TCP, l'handshake SSL o il trasferimento dati.

Cause

Le cause tipiche includono: server lento o sovraccarico che non risponde in tempo, congestione di rete o perdita di pacchetti, firewall che scarta silenziosamente i pacchetti (nessun rifiuto, solo silenzio), valori di timeout troppo restrittivi impostati con --connect-timeout o --max-time, oppure una configurazione proxy errata che causa ritardi.

Come risolvere

Aumenta il timeout: curl --connect-timeout 30 --max-time 120 URL. Usa la modalità verbosa per vedere dove si blocca: curl -v URL. Testa la latenza di rete: ping api.example.com e traceroute api.example.com. Se sei dietro un proxy, prova a bypassarlo: curl --noproxy '*' URL. Per trasferimenti di file grandi, considera l'uso di --retry 3 con --retry-delay 5.

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

Errore 35: Errore di connessione SSL

Cosa significa

Il tuo terminale mostra curl: (35) SSL connect error. L'handshake SSL/TLS è fallito — curl non è riuscito a stabilire una connessione sicura con il server.

Cause

Le cause comuni sono: mismatch nella versione TLS (il server richiede TLS 1.3 ma il tuo curl supporta solo TLS 1.2), incompatibilità della suite di cifratura, configurazione SSL errata del server (certificato scaduto presentato durante l'handshake, catena incompleta), il server non supporta effettivamente HTTPS sulla porta specificata, oppure un proxy o firewall sta intercettando la connessione SSL (MITM).

Come risolvere

Forza una versione TLS specifica: curl --tlsv1.2 URL o curl --tlsv1.3 URL. Verifica cosa supporta il server: openssl s_client -connect api.example.com:443. Aggiorna curl e OpenSSL all'ultima versione. Se il server usa un certificato self-signed, di solito è l'errore 60 — l'errore 35 indica tipicamente un fallimento dell'handshake a livello di protocollo.

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

Errore 56: Errore di ricezione — Connessione resettata

Cosa significa

Il tuo terminale mostra curl: (56) Recv failure: Connection reset by peer. La connessione è stata stabilita con successo, ma la ricezione dei dati è fallita — il server ha chiuso o resettato la connessione inaspettatamente durante il trasferimento.

Cause

Questo accade spesso quando: il server si blocca o si riavvia durante il trasferimento, un load balancer o proxy interrompe la connessione (timeout di inattività, richiesta troppo grande), un firewall termina le connessioni di lunga durata, il server ha un timeout keep-alive più breve del previsto, oppure c'è un'interruzione di rete tra client e server.

Come risolvere

Riprova la richiesta — i problemi di rete transitori sono la causa più comune. Usa la modalità verbosa: curl -v URL per vedere il punto esatto del fallimento. Se l'errore si verifica durante caricamenti di grandi dimensioni, prova il trasferimento chunked: curl -H "Transfer-Encoding: chunked" URL. Per operazioni Git che mostrano RPC failed; curl 56, aumenta il buffer: git config http.postBuffer 524288000.

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

Errore 60: Problema con il certificato SSL

Cosa significa

Il tuo terminale mostra curl: (60) SSL certificate problem: unable to get local issuer certificate. curl non è riuscito a verificare il certificato SSL del server rispetto al proprio bundle CA (Certificate Authority). L'handshake TLS è stato completato a livello di protocollo, ma la validazione del certificato è fallita.

Cause

Le cause più comuni sono: il server utilizza un certificato self-signed, il certificato è scaduto, la catena di certificati è incompleta (mancano i certificati intermedi), il bundle CA di curl è obsoleto (comune su sistemi vecchi o nei container Docker), oppure il Common Name / SAN del certificato non corrisponde al nome host richiesto.

Come risolvere

Aggiorna il bundle CA: curl --cacert /path/to/cacert.pem URL. Scarica un bundle aggiornato da https://curl.se/ca/cacert.pem. Per diagnosticare: openssl s_client -connect api.example.com:443 -showcerts. Per certificati self-signed in sviluppo, usa curl -k URL (mai in produzione — disabilita tutta la verifica dei certificati). In Docker, installa il pacchetto ca-certificates.

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

Altri codici di errore

Come eseguire il debug degli errori curl

Quando curl fallisce, questi tre flag ti aiutano a identificare rapidamente la causa principale — dalla risoluzione DNS all'handshake SSL fino al payload della risposta.

1. 1

   Abilita l'output verboso

   Esegui curl -v URL per vedere l'intero ciclo richiesta/risposta: risoluzione DNS, connessione TCP, handshake TLS, header della richiesta inviati e header della risposta ricevuti. Questo è il flag di debug più utile in assoluto.

2. 2

   Controlla il codice di stato HTTP

   Esegui curl -o /dev/null -s -w "%{http_code}" URL per ottenere solo il codice di stato HTTP (200, 404, 500, ecc.) senza il corpo della risposta. Utile per controlli rapidi di stato e per gli script.

3. 3

   Mostra gli errori silenziosamente

   Esegui curl -sS URL per sopprimere la barra di avanzamento (-s) ma mostrare comunque gli errori (-S). Perfetto per script dove vuoi un output pulito ma devi catturare i fallimenti.

Domande frequenti