Rede
Referência de Códigos de Saída do curl
Referência completa dos exit code (códigos de saída) do comando curl: significados, causas comuns e soluções para desenvolvedores que depuram pipelines de CI/CD e scripts de shell. Inclui uma ferramenta de consulta: digite um número de código para ver os detalhes instantaneamente.
Tabela de Referência de Exit Codes do curl
| Código | Nome da Constante | Significado | Causas Comuns |
|---|---|---|---|
| Erros de Conexão / Inicialização | |||
| 1 | CURLE_UNSUPPORTED_PROTOCOL | Indica que o curl não suporta o protocolo especificado na URL. | Ocorre ao usar um binário do curl compilado sem esse protocolo habilitado (por exemplo, gopher, ldap), ou por um erro de digitação no esquema da URL. |
| 2 | CURLE_FAILED_INIT | Indica que a inicialização interna do curl falhou. | Uma falha de inicialização de baixo nível pouco frequente, geralmente causada por memória insuficiente ou um ambiente anômalo. |
| 3 | CURLE_URL_MALFORMAT | Indica que a URL especificada está malformada e o curl não consegue interpretá-la. | Ocorre quando falta o esquema na URL (por exemplo, http://) ou ela contém caracteres inválidos. |
| 5 | CURLE_COULDNT_RESOLVE_PROXY | Indica que o curl não conseguiu resolver o nome de host do servidor proxy especificado. | Causado por um erro de digitação no nome de host passado para --proxy, ou uma falha de DNS específica do proxy. |
| 6 | CURLE_COULDNT_RESOLVE_HOST | Indica que o curl não conseguiu resolver (DNS) o nome de host do servidor de destino. | Geralmente causado por um erro de digitação no nome de domínio, uma falha no servidor DNS, ou a execução em um ambiente offline. |
| 7 | CURLE_COULDNT_CONNECT | Indica que o nome de host foi resolvido, mas o curl não conseguiu estabelecer uma conexão TCP com o servidor. | Ocorre por um número de porta incorreto, um firewall bloqueando a conexão, ou porque o servidor está fora do ar. |
| 8 | CURLE_WEIRD_SERVER_REPLY | Indica que o curl recebeu uma resposta inesperada do servidor que não conseguiu interpretar. | Comum quando um servidor FTP retorna uma resposta não padrão, ou quando o curl se conecta acidentalmente a um servidor que fala outro protocolo. |
| 9 | CURLE_REMOTE_ACCESS_DENIED | Indica que o curl se conectou ao servidor, mas o acesso foi negado. | Ocorre por permissões insuficientes em um diretório FTP, ou quando o servidor aplica uma restrição de IP. |
| Erros de Transferência de Dados | |||
| 18 | CURLE_PARTIAL_FILE | Indica que a transferência foi interrompida antes de ser concluída, de modo que apenas parte do arquivo foi recebida. | Ocorre por uma breve interrupção de rede, ou quando o servidor encerra a conexão antes de atingir o Content-Length anunciado. |
| 23 | CURLE_WRITE_ERROR | Indica que o curl não conseguiu gravar dados no disco local ou no destino do callback. | Ocorre quando o disco está cheio, ou o curl não tem permissão de gravação no arquivo de saída. |
| 26 | CURLE_READ_ERROR | Indica que o curl não conseguiu ler o arquivo local a ser enviado. | Ocorre quando o arquivo especificado com -T/--upload-file não existe, ou o curl não tem permissão de leitura sobre ele. |
| 52 | CURLE_GOT_NOTHING | Indica que o curl se conectou ao servidor, mas não recebeu nenhuma resposta. | Geralmente causado pelo processo do servidor travando no meio da requisição, ou por uma configuração incorreta que retorna uma resposta vazia. |
| 55 | CURLE_SEND_ERROR | Indica que o curl não conseguiu enviar dados pela rede. | Ocorre quando o lado remoto se desconecta imediatamente após a conexão ser estabelecida, ou por um problema na interface de rede local. |
| 56 | CURLE_RECV_ERROR | Indica que o curl não conseguiu receber dados da rede. | Frequentemente observado quando o lado remoto reinicia inesperadamente a conexão no meio da transferência (Connection reset by peer). |
| 63 | CURLE_FILESIZE_EXCEEDED | Indica que o tamanho do arquivo excedeu o limite definido com --max-filesize. | Ocorre quando a resposta acaba sendo maior do que o esperado e atinge o limite de segurança configurado. |
| 78 | CURLE_REMOTE_FILE_NOT_FOUND | Indica que o arquivo especificado não existe no servidor remoto (por exemplo, FTP). | Ocorre por um erro de digitação no caminho FTP, ou porque o arquivo alvo já foi excluído ou movido. |
| Erros de Certificado SSL/TLS | |||
| 35 | CURLE_SSL_CONNECT_ERROR | Indica que ocorreu um problema durante o handshake SSL/TLS, impedindo o estabelecimento da conexão. | Geralmente causado por uma incompatibilidade entre as versões de TLS ou os conjuntos de cifra suportados pelo servidor e pelo cliente. |
| 51 | CURLE_PEER_FAILED_VERIFICATION | Indica que a verificação do certificado do servidor falhou (por exemplo, o certificado não corresponde ao nome de host). | Ocorre ao acessar um certificado autoassinado, ou quando o Common Name/SAN do certificado difere do nome de host de destino. |
| 58 | CURLE_SSL_CERTPROBLEM | Indica um problema com o certificado de cliente especificado localmente. | Geralmente causado por um formato inválido no arquivo de certificado passado com --cert, ou uma senha (passphrase) incorreta. |
| 60 | CURLE_SSL_CACERT | Indica que o curl não conseguiu verificar a cadeia de certificados da CA usada para validar o certificado do servidor. | Ocorre quando o pacote de certificados da CA está desatualizado, ou uma CA autoassinada (como a de um proxy corporativo) não está registrada no repositório de confiança. -k/--insecure é uma solução alternativa, mas não é recomendada para uso em produção. |
| Erros de HTTP / Autenticação | |||
| 22 | CURLE_HTTP_RETURNED_ERROR | Indica que, com a opção -f/--fail especificada, a resposta HTTP retornou um status de erro igual ou superior a 400. | Provocado intencionalmente em scripts de CI/CD que usam curl -f para detectar como falha um status de erro da API. |
| 67 | CURLE_LOGIN_DENIED | Indica que o login (autenticação) no servidor foi recusado. | Geralmente causado por um nome de usuário ou senha incorretos, ou um bloqueio de conta em protocolos como FTP/SMTP. |
| Outros | |||
| 27 | CURLE_OUT_OF_MEMORY | Indica que o curl falhou ao alocar memória durante a execução. | Uma situação rara, como tentar processar um arquivo enorme em um sistema com memória limitada. |
| 28 | CURLE_OPERATION_TIMEDOUT | Indica que a operação não foi concluída dentro do limite de tempo definido com --connect-timeout/--max-time, etc. | Um dos erros mais frequentes em CI, causado por uma resposta lenta do servidor, latência de rede, ou um valor de timeout definido curto demais. |
| 47 | CURLE_TOO_MANY_REDIRECTS | Indica que o número de redirecionamentos excedeu o limite definido com --max-redirs. | Ocorre com um loop de redirecionamento (301/302 redirecionando de forma circular), ou uma cadeia de redirecionamentos legítima mais longa que o limite padrão (50). |
Dicas
- Você pode verificar o exit code imediatamente com
$?(Bash) ou%errorlevel%(Windows). Em scripts de shell, uma ramificação comocurl ... || echo "failed with $?"é bastante prática. - 28 (timeout) e 7 (falha de conexão) costumam ser confundidos, mas o 28 ocorre quando a resposta é lenta após a conexão ser estabelecida, enquanto o 7 ocorre quando a própria conexão TCP nunca chega a ser estabelecida.
- Se você receber um 60 (erro de certificado de CA), não contorne o problema simplesmente com
-k/--insecure— primeiro verifique se o pacote de certificados de CA (ca-certificates) está atualizado. Usar -k rotineiramente em produção aumenta o risco de ataques man-in-the-middle. - O 22 (erro HTTP) só ocorre quando você adiciona a opção
-f/--fail. Sem ela, o curl retorna exit code 0 (sucesso) mesmo para uma resposta 404 ou 500, então sempre adicione -f se quiser que o CI detecte falhas.
Perguntas Frequentes
Logo após executar o comando curl, verifique com
echo $? no Bash/Zsh, echo %errorlevel% no Prompt de Comando do Windows, ou $LASTEXITCODE no PowerShell.Primeiro revise as configurações de
--connect-timeout e --max-time e as aumente se necessário. Se o servidor responder lentamente de forma constante, verifique também a carga do servidor e o caminho de rede (proxies, VPNs, etc.).Não, são coisas diferentes. Os códigos de status HTTP (como 404 ou 500) são respostas em nível de protocolo retornadas pelo servidor, enquanto os exit codes do curl indicam o resultado da execução do próprio comando curl (falha de conexão, timeout, etc.). Por padrão, o curl trata erros HTTP como exit code 0 (sucesso), então é preciso ter cuidado para não confundir os dois.
Adicione a opção
curl -f (--fail) para que o curl retorne exit code 22 sempre que a resposta HTTP for igual ou superior a 400. Sem ela, obter com sucesso uma página de erro ainda resultará em exit code 0.O 6 (COULDNT_RESOLVE_HOST) é um erro na fase de DNS, quando o nome de host não pode ser resolvido para um endereço IP. O 7 (COULDNT_CONNECT) é um erro em que a resolução de nomes teve sucesso, mas não foi possível estabelecer a conexão TCP com esse endereço IP.
Curiosidade — O sistema de exit codes do curl
O curl é uma ferramenta de linha de comando cujo desenvolvimento começou em 1996 por Daniel Stenberg, originalmente sob o nome "httpget". Hoje o curl vem instalado por padrão em praticamente todas as distribuições Linux, no macOS e no Windows 10 em diante, tornando-se uma das ferramentas mais fundamentais para desenvolvedores web.
O sistema de exit codes corresponde diretamente ao enum de erros interno da libcurl, CURLcode, e é definido com uma numeração sequencial que começa em `CURLE_OK` (sucesso, exit code 0). As lacunas na numeração existem porque alguns códigos de erro foram descontinuados ou unificados ao longo do desenvolvimento.
Curiosamente, os exit codes do curl formam um sistema próprio, independente da convenção geral do POSIX (0 = sucesso, 1 = erro geral). Isso significa que, ao lidar com os exit codes de várias ferramentas em um script de shell, é necessário consultar o manual de cada uma separadamente para entender seu significado.