Codici di Uscita curl (Exit Code 1-99): Riferimento e Rimedi

Riferimento per i codici di uscita e return code di curl, da 1 a 99: cercate un codice, ad esempio il 22, il 3, il 28 o il 52, e trovate significato, cause più frequenti e rimedio esatto. Alternativa rapida alla documentazione ufficiale per il debug in CI/CD, cron e script.

Tabella dei codici di uscita di curl

Codice	Nome della costante	Significato	Cause più frequenti
Errori di connessione e inizializzazione
1	CURLE_UNSUPPORTED_PROTOCOL	Indica che curl non supporta il protocollo indicato nell'indirizzo.	Si sta usando un eseguibile di curl compilato senza quel protocollo, per esempio gopher o ldap, oppure c'è un errore di digitazione nello schema dell'indirizzo.
2	CURLE_FAILED_INIT	Indica il fallimento dell'inizializzazione interna di curl.	Un errore di basso livello, raro, dovuto a memoria insufficiente o ad anomalie dell'ambiente.
3	CURLE_URL_MALFORMAT	Indica che l'indirizzo indicato ha un formato scorretto che curl non riesce a interpretare.	Si verifica quando manca lo schema, per esempio il prefisso http://, o quando l'indirizzo contiene caratteri non ammessi.
5	CURLE_COULDNT_RESOLVE_PROXY	Indica il fallimento della risoluzione del nome host del servente intermediario.	Nome host errato nell'opzione --proxy oppure impossibilità di risolvere il nome tramite il sistema dei nomi previsto per l'intermediario.
6	CURLE_COULDNT_RESOLVE_HOST	Indica il fallimento della risoluzione del nome dell'host di destinazione.	Errore di digitazione nel nome di dominio, guasto del servente dei nomi o esecuzione in un ambiente privo di connessione.
7	CURLE_COULDNT_CONNECT	Indica che il nome è stato risolto ma non è stato possibile stabilire la connessione TCP con il servente.	Numero di porta errato, blocco da parte del filtro di rete o servente non in funzione.
8	CURLE_WEIRD_SERVER_REPLY	Indica la ricezione dal servente di una risposta inattesa, che curl non riesce a interpretare.	Si verifica facilmente quando un servente FTP restituisce una risposta non conforme allo standard o quando ci si collega per errore a un servente che parla un altro protocollo.
9	CURLE_REMOTE_ACCESS_DENIED	Indica che la connessione al servente è riuscita ma l'accesso è stato negato.	Permessi insufficienti su una cartella FTP oppure restrizioni per indirizzo IP imposte dal servente.
Errori di trasferimento dei dati
18	CURLE_PARTIAL_FILE	Indica che il trasferimento è stato interrotto prima del termine e il file è stato ricevuto solo in parte.	Un'interruzione momentanea della rete oppure la chiusura della connessione da parte del servente prima della lunghezza annunciata nell'intestazione Content-Length.
23	CURLE_WRITE_ERROR	Indica il fallimento della scrittura dei dati sul disco locale o verso la funzione di richiamo.	Spazio su disco insufficiente o mancanza dei permessi di scrittura sul file di destinazione.
26	CURLE_READ_ERROR	Indica il fallimento della lettura del file locale da caricare.	Il file indicato con -T o --upload-file non esiste oppure mancano i permessi di lettura.
52	CURLE_GOT_NOTHING	Indica che la connessione al servente è riuscita ma non è giunta alcuna risposta.	Il processo del servente si è interrotto durante l'elaborazione della richiesta oppure una configurazione difettosa gli fa restituire una risposta vuota.
55	CURLE_SEND_ERROR	Indica il fallimento dell'invio dei dati sulla rete.	La controparte ha chiuso la connessione subito dopo averla stabilita, oppure c'è un'anomalia nell'interfaccia di rete locale.
56	CURLE_RECV_ERROR	Indica il fallimento della ricezione dei dati dalla rete.	Si osserva soprattutto quando la controparte reimposta inaspettatamente la connessione durante lo scambio.
63	CURLE_FILESIZE_EXCEEDED	Indica che la dimensione del file supera il limite fissato con --max-filesize.	Si verifica quando si tenta di scaricare una risposta più voluminosa del previsto e scatta il limite impostato per prudenza.
78	CURLE_REMOTE_FILE_NOT_FOUND	Indica che il file richiesto non esiste sul servente remoto, per esempio in FTP.	Errore di digitazione nel percorso FTP oppure file già eliminato o spostato.
Errori dei certificati SSL/TLS
35	CURLE_SSL_CONNECT_ERROR	Indica che durante la negoziazione SSL/TLS si è verificato un problema e la connessione non è stata stabilita.	Si verifica facilmente quando servente e cliente non condividono alcuna versione di TLS o alcuna suite crittografica.
51	CURLE_PEER_FAILED_VERIFICATION	Indica il fallimento della verifica del certificato del servente, per esempio perché non corrisponde al nome host.	Accesso a un certificato autofirmato oppure nome comune o nome alternativo del certificato diverso dal nome host di destinazione.
58	CURLE_SSL_CERTPROBLEM	Indica un problema nel certificato del cliente indicato localmente.	Formato non valido del file indicato con --cert oppure errore nell'inserimento della frase d'accesso.
60	CURLE_SSL_CACERT	Indica l'impossibilità di verificare la catena di certificati dell'autorità necessaria a convalidare quello del servente.	Insieme dei certificati delle autorità non aggiornato oppure autorità autofirmata, per esempio quella di un intermediario aziendale, non presente fra quelle attendibili. Esiste il ripiego -k, ossia --insecure, ma se ne sconsiglia l'uso in produzione.
Errori HTTP e di autenticazione
22	CURLE_HTTP_RETURNED_ERROR	Indica che, con l'opzione -f o --fail attiva, la risposta HTTP recava uno stato d'errore della serie 400 o superiore.	Si provoca di proposito, per rilevare gli errori, quando negli script dell'integrazione continua si usa curl -f e l'interfaccia risponde con uno stato d'errore.
67	CURLE_LOGIN_DENIED	Indica che l'accesso al servente, cioè l'autenticazione, è stato rifiutato.	Nome utente o parola d'ordine errati, oppure blocco dell'utenza su servizi come FTP o SMTP.
Altri
27	CURLE_OUT_OF_MEMORY	Indica il fallimento dell'allocazione di memoria durante l'esecuzione di curl.	Situazione rara, per esempio il tentativo di trattare file enormi in un ambiente con poca memoria.
28	CURLE_OPERATION_TIMEDOUT	Indica che l'operazione non si è conclusa entro il limite di tempo fissato con --connect-timeout, --max-time o simili.	Risposta lenta del servente, latenza di rete o limite di tempo troppo stretto: è uno degli errori più frequenti nell'integrazione continua.
47	CURLE_TOO_MANY_REDIRECTS	Indica il superamento del numero massimo di reindirizzamenti fissato con --max-redirs.	Un ciclo di reindirizzamenti, con risposte 301 o 302 che si rincorrono, oppure una catena legittima più lunga del limite predefinito di cinquanta.

Cos'è un exit code di curl?

Un exit code di curl è il numero che curl restituisce alla shell (consultabile con $?) al termine dell'esecuzione, e indica se la richiesta è andata a buon fine e, in caso contrario, il motivo. A differenza del codice di stato HTTP restituito dal server, l'exit code descrive l'esito del comando curl stesso: errore DNS, timeout di connessione, errore di handshake SSL e così via.

Questo strumento permette di cercare qualsiasi exit code (1-99) per visualizzarne il significato e le cause più frequenti, oppure di filtrare la tabella di riferimento completa per codice, nome della costante o parola chiave. È pensato per il debug degli errori di curl in pipeline CI/CD, cron job o script di shell che chiamano API o scaricano file.

Come usare questo strumento

Inserisci il numero dell'exit code Digita nel campo di ricerca il codice ottenuto con echo $? dopo un comando curl fallito.
Consulta il significato e le cause frequenti Lo strumento mostra cosa indica il codice e in quali situazioni si verifica tipicamente.
Filtra la tabella completa Se non conosci il numero esatto, filtra la tabella di riferimento per parola chiave.
Verifica il rimedio suggerito Usa le cause frequenti come punto di partenza per applicare la correzione più adatta al tuo script o ambiente.

Consigli per sfruttarlo al meglio

Il codice di uscita si legge subito dopo con $? in Bash o %errorlevel% in Windows. Negli script di shell è comodo usarlo per le diramazioni, per esempio con curl ... || echo "fallito con $?".
Il 28, cioè il tempo scaduto, e il 7, cioè la connessione fallita, si confondono facilmente: il 28 riguarda una risposta lenta dopo la connessione, il 7 il caso in cui la connessione TCP non si stabilisce affatto.
Di fronte al 60, l'errore del certificato dell'autorità, non aggirate il problema con -k o --insecure: verificate anzitutto che l'insieme dei certificati delle autorità sia aggiornato. L'uso abituale di -k in produzione aumenta il rischio di attacchi con interposizione.
Il 22, l'errore HTTP, si presenta soltanto con l'opzione -f o --fail. Senza di essa curl restituisce il codice di uscita 0, cioè successo, anche ricevendo un 404 o un 500: per rilevare gli insuccessi nell'integrazione continua aggiungete sempre -f.

Casi d'uso

Debug di uno step fallito in una pipeline CI/CD

Individua rapidamente perché uno step di deploy o health-check basato su curl è fallito, cercando l'exit code nel log di build.

Diagnosi di un cron job che fallisce silenziosamente

I cron job raramente mostrano output: controllare l'exit code registrato è spesso il modo più rapido per trovare la causa.

Gestione robusta degli errori negli script di shell

Verifica quali codici indicano un problema di rete che vale la pena ritentare rispetto a un errore permanente, per ramificare la logica dello script.

Analisi post-incidente (postmortem)

Conferma con precisione quale tipo di errore (DNS, TLS, timeout) si è verificato, rivedendo i log dopo un'interruzione.

Imparare le basi di curl e delle reti

Usa la tabella per capire sistematicamente in quale fase di un trasferimento (risoluzione, connessione, TLS, trasferimento) può verificarsi un errore.

Glossario

Exit code: Il numero che un programma restituisce alla shell alla chiusura. 0 significa successo; curl usa 1-99 per indicare tipi di errore specifici.
CURLcode: L'enum interno di libcurl che definisce ogni tipo di errore. Gli exit code della riga di comando di curl corrispondono direttamente a questo enum.
libcurl: La libreria C che implementa la logica di trasferimento principale di curl. Il tool a riga di comando curl ne è solo un sottile wrapper.
Opzione --fail / -f: Un'opzione di curl che fa sì che le risposte di errore HTTP (400 e superiori) producano l'exit code 22 invece dell'exit code 0 predefinito.
Timeout e connessione rifiutata: Il timeout (28) significa che nessuna risposta è arrivata in tempo; il rifiuto/errore di connessione (7) significa che la connessione TCP stessa non è stata stabilita.
Risoluzione DNS: Il processo che converte un nome host in un indirizzo IP. Se fallisce, curl restituisce l'exit code 6.
Handshake SSL/TLS: Il processo con cui client e server stabiliscono una connessione cifrata. I problemi in questa fase producono tipicamente gli exit code 35, 51, 58 o 60.

Domande frequenti

Subito dopo l'esecuzione del comando: con echo $? in Bash e Zsh, con echo %errorlevel% nel prompt dei comandi di Windows e con $LASTEXITCODE in PowerShell.

Rivedete anzitutto i valori di --connect-timeout e --max-time, allungandoli se necessario. Se la lentezza del servente è costante, verificate anche il suo carico di lavoro e il percorso di rete, compresi eventuali intermediari o reti private virtuali.

No, sono due cose diverse. Il codice di stato HTTP, per esempio 404 o 500, è la risposta a livello di protocollo restituita dal servente; il codice di uscita di curl riguarda l'esito dell'esecuzione del comando stesso, come una connessione fallita o un tempo scaduto. Poiché curl considera per impostazione predefinita gli errori HTTP come codice di uscita 0, cioè successo, occorre attenzione a non confonderli.

Aggiungendo l'opzione curl -f, ossia --fail, il comando restituisce il codice di uscita 22 quando la risposta HTTP appartiene alla serie 400 o superiore. Senza quell'opzione, il semplice fatto di aver scaricato correttamente una pagina d'errore produce un codice di uscita pari a 0.

Il 6, COULDNT_RESOLVE_HOST, è l'errore della fase in cui il sistema dei nomi non riesce a tradurre il nome host in un indirizzo IP; il 7, COULDNT_CONNECT, è quello della fase successiva, in cui la risoluzione è riuscita ma non si stabilisce la connessione TCP verso quell'indirizzo.

A proposito — l'ordinamento dei codici di uscita di curl

curl è uno strumento a riga di comando il cui sviluppo cominciò nel 1996 per opera di Daniel Stenberg; all'inizio si chiamava «httpget». Oggi è presente di serie in praticamente tutte le distribuzioni Linux, in macOS e in Windows a partire dalla versione 10, ed è uno degli strumenti più elementari per chi sviluppa per il web.

L'ordinamento dei codici di uscita corrisponde esattamente all'enumerazione interna degli errori di libcurl, CURLcode, definita come una successione numerata che comincia da CURLE_OK, cioè il successo, con codice di uscita 0. I numeri mancanti si spiegano con i codici d'errore che nel corso dello sviluppo sono stati sconsigliati o accorpati.

È interessante notare che i codici di uscita di curl seguono un ordinamento proprio, indipendente dalla consuetudine POSIX secondo cui 0 indica il successo e 1 un errore generico. Quando in uno script di shell si trattano insieme i codici di uscita di più comandi occorre perciò verificarne il significato sul manuale di ciascuno strumento.

Vedi tutte le curiosità