Códigos de Erro do curl: Referência Completa

Quando um comando curl falha, ele retorna um código de saída numérico (também chamado de código de erro do curl) que identifica o tipo de erro. Você pode verificar o código de saída do curl executando echo $? imediatamente após o comando curl (ou $LASTEXITCODE no PowerShell). O código de saída 0 significa sucesso; qualquer outro número indica um problema específico — desde falhas de resolução DNS e timeouts de conexão até problemas com certificados SSL. Esta página é uma referência completa dos códigos de erro do curl mais comuns com explicações, causas e correções. Se você está trabalhando com comandos curl no seu código, cole-os no curl2code para converter para a linguagem de programação de sua preferência.

Tabela de Referência Rápida

Código de Saída	Nome do Erro	Descrição
0	CURLE_OK	Sucesso. A operação foi concluída sem erros.
1	CURLE_UNSUPPORTED_PROTOCOL	Protocolo não suportado. A URL usa um protocolo que o curl não foi compilado para suportar.
3	CURLE_URL_MALFORMAT	URL malformada. A sintaxe da URL é inválida ou não pôde ser analisada.
5	CURLE_COULDNT_RESOLVE_PROXY	Não foi possível resolver o proxy. O hostname do proxy especificado não pôde ser resolvido.
6	CURLE_COULDNT_RESOLVE_HOST	Consulta DNS falhou — o hostname não pôde ser resolvido para um endereço IP.
7	CURLE_COULDNT_CONNECT	Conexão TCP falhou — servidor fora do ar, porta bloqueada ou firewall rejeitando conexões.
18	CURLE_PARTIAL_FILE	Arquivo parcial. A transferência foi interrompida e apenas parte do arquivo foi recebida.
22	CURLE_HTTP_RETURNED_ERROR	Servidor retornou um erro HTTP (4xx/5xx) e a flag --fail foi usada.
23	CURLE_WRITE_ERROR	Erro de escrita. O curl falhou ao gravar dados recebidos no disco (permissão negada ou disco cheio).
28	CURLE_OPERATION_TIMEDOUT	A operação excedeu o tempo máximo permitido (DNS, conexão ou transferência).
35	CURLE_SSL_CONNECT_ERROR	Handshake SSL/TLS falhou — incompatibilidade de versão do protocolo ou cipher suite.
37	CURLE_FILE_COULDNT_READ_FILE	Não foi possível ler o arquivo. Um arquivo local referenciado na requisição não pôde ser aberto ou lido.
52	CURLE_GOT_NOTHING	Resposta vazia do servidor. O servidor fechou a conexão sem enviar nenhum dado.
56	CURLE_RECV_ERROR	Conexão foi redefinida — o servidor derrubou a conexão durante a transferência de dados.
60	CURLE_SSL_CACERT	Verificação de certificado SSL falhou — expirado, autoassinado ou pacote de CA desatualizado.
77	CURLE_SSL_CACERT_BADFILE	Problema com certificado CA SSL. Não foi possível ler ou analisar o arquivo de certificado CA especificado.
92	CURLE_HTTP2_STREAM	Erro de stream HTTP/2. Ocorreu um erro de protocolo HTTP/2 no nível do stream durante a transferência.

0CURLE_OK

Sucesso. A operação foi concluída sem erros.

1CURLE_UNSUPPORTED_PROTOCOL

Protocolo não suportado. A URL usa um protocolo que o curl não foi compilado para suportar.

3CURLE_URL_MALFORMAT

URL malformada. A sintaxe da URL é inválida ou não pôde ser analisada.

5CURLE_COULDNT_RESOLVE_PROXY

Não foi possível resolver o proxy. O hostname do proxy especificado não pôde ser resolvido.

6CURLE_COULDNT_RESOLVE_HOST

Consulta DNS falhou — o hostname não pôde ser resolvido para um endereço IP.

7CURLE_COULDNT_CONNECT

Conexão TCP falhou — servidor fora do ar, porta bloqueada ou firewall rejeitando conexões.

18CURLE_PARTIAL_FILE

Arquivo parcial. A transferência foi interrompida e apenas parte do arquivo foi recebida.

22CURLE_HTTP_RETURNED_ERROR

Servidor retornou um erro HTTP (4xx/5xx) e a flag --fail foi usada.

23CURLE_WRITE_ERROR

Erro de escrita. O curl falhou ao gravar dados recebidos no disco (permissão negada ou disco cheio).

28CURLE_OPERATION_TIMEDOUT

A operação excedeu o tempo máximo permitido (DNS, conexão ou transferência).

35CURLE_SSL_CONNECT_ERROR

Handshake SSL/TLS falhou — incompatibilidade de versão do protocolo ou cipher suite.

37CURLE_FILE_COULDNT_READ_FILE

Não foi possível ler o arquivo. Um arquivo local referenciado na requisição não pôde ser aberto ou lido.

52CURLE_GOT_NOTHING

Resposta vazia do servidor. O servidor fechou a conexão sem enviar nenhum dado.

56CURLE_RECV_ERROR

Conexão foi redefinida — o servidor derrubou a conexão durante a transferência de dados.

60CURLE_SSL_CACERT

Verificação de certificado SSL falhou — expirado, autoassinado ou pacote de CA desatualizado.

77CURLE_SSL_CACERT_BADFILE

Problema com certificado CA SSL. Não foi possível ler ou analisar o arquivo de certificado CA especificado.

92CURLE_HTTP2_STREAM

Erro de stream HTTP/2. Ocorreu um erro de protocolo HTTP/2 no nível do stream durante a transferência.

Erro 6: Não Foi Possível Resolver o Host

O que significa: Seu terminal exibe curl: (6) Could not resolve host. O curl não conseguiu resolver o hostname para um endereço IP — a consulta DNS falhou antes de qualquer tentativa de conexão.
Causas: As causas mais comuns são: um erro de digitação no hostname (ex.: curl https://apiexample.com em vez de api.example.com), problemas no servidor DNS (seu DNS configurado está fora do ar ou inacessível), sem conexão de rede (Wi-Fi desconectado, VPN não conectada) ou o domínio genuinamente não existe.
Como corrigir: Primeiro, verifique se a URL está correta. Depois teste a resolução DNS diretamente: nslookup api.example.com ou dig api.example.com. Se o DNS falhar, tente um servidor DNS diferente: curl --dns-servers 8.8.8.8 https://api.example.com. Verifique seu /etc/resolv.conf ou configurações de rede. Se estiver atrás de uma VPN corporativa, certifique-se de que o DNS interno consegue resolver o host.

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

Erro 7: Falha ao Conectar

O que significa: Seu terminal exibe curl: (7) Failed to connect to host port: Connection refused. O curl resolveu o hostname mas não conseguiu estabelecer uma conexão TCP com o servidor — a conexão foi ativamente recusada ou expirou no nível TCP.
Causas: Causas comuns incluem: o servidor está fora do ar ou não está em execução, um firewall está bloqueando a porta (verifique tanto o firewall local quanto o do servidor), a porta está errada (ex.: o serviço roda na 8080 mas você está conectando na 443) ou o backlog de escuta do servidor está cheio sob carga pesada.
Como corrigir: Verifique se o servidor está rodando: ping api.example.com e telnet api.example.com 443. Verifique se a porta correta está aberta: nmap -p 443 api.example.com. Desative o firewall local temporariamente para testar. Se estiver usando Docker, certifique-se de que a porta do container está publicada. Tente com modo verbose: curl -v https://api.example.com para ver exatamente onde a conexão falha.

$ curl https://localhost:8080/api

Erro 22: HTTP Retornou Erro

O que significa: Seu terminal exibe curl: (22) The requested URL returned error. O servidor retornou um código de status HTTP de erro (4xx ou 5xx) e o curl foi invocado com -f ou --fail, que instrui o curl a tratar erros HTTP como falhas.
Causas: O erro é disparado por códigos de status HTTP como 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) ou 500 (Internal Server Error) — mas somente quando --fail é usado. Sem --fail, o curl sai com código 0 mesmo em erros HTTP. Causas comuns: URL errada, autenticação ausente, permissões insuficientes ou bugs no servidor.
Como corrigir: Execute o curl sem --fail para ver o corpo completo da resposta — ele frequentemente contém a mensagem de erro real. Verifique o código de status HTTP: curl -w "%{http_code}" -o /dev/null -s URL. Para 401/403: verifique seu token de autenticação ou chave de API. Para 404: confira o caminho da URL. Para 500: o problema é no servidor.

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

Erro 28: Operação Expirou (Timeout)

O que significa: Seu terminal exibe curl: (28) Operation timed out ou curl: (28) Connection timed out. A operação demorou mais que o tempo permitido. Este é o erro de curl mais comum — pode ocorrer durante a resolução DNS, conexão TCP, handshake SSL ou transferência de dados.
Causas: Causas típicas incluem: servidor lento ou sobrecarregado não respondendo a tempo, congestionamento de rede ou perda de pacotes, firewall descartando pacotes silenciosamente (sem rejeição, apenas silêncio), valores de timeout muito restritos definidos com --connect-timeout ou --max-time, ou uma configuração incorreta de proxy causando atrasos.
Como corrigir: Aumente o timeout: curl --connect-timeout 30 --max-time 120 URL. Use o modo verbose para ver onde ele trava: curl -v URL. Teste a latência da rede: ping api.example.com e traceroute api.example.com. Se estiver atrás de um proxy, tente ignorá-lo: curl --noproxy '*' URL. Para transferências de arquivos grandes, considere usar --retry 3 com --retry-delay 5.

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

Erro 35: Erro de Conexão SSL

O que significa: Seu terminal exibe curl: (35) SSL connect error. O handshake SSL/TLS falhou — o curl não conseguiu estabelecer uma conexão segura com o servidor.
Causas: Causas comuns: incompatibilidade de versão TLS (servidor requer TLS 1.3 mas seu curl suporta apenas até TLS 1.2), incompatibilidade de cipher suite, configuração SSL incorreta do servidor (certificado expirado apresentado durante o handshake, cadeia incompleta), o servidor na verdade não suporta HTTPS na porta informada, ou um proxy ou firewall está interceptando a conexão SSL (MITM).
Como corrigir: Force uma versão TLS específica: curl --tlsv1.2 URL ou curl --tlsv1.3 URL. Verifique o que o servidor suporta: openssl s_client -connect api.example.com:443. Atualize o curl e o OpenSSL para as versões mais recentes. Se o servidor usa um certificado autoassinado, geralmente é o erro 60 — o erro 35 normalmente indica uma falha de handshake no nível do protocolo.

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

Erro 56: Falha de Recebimento — Conexão Foi Redefinida

O que significa: Seu terminal exibe curl: (56) Recv failure: Connection reset by peer. A conexão foi estabelecida com sucesso, mas a recepção de dados falhou — o servidor fechou ou redefiniu a conexão inesperadamente durante a transferência.
Causas: Isso frequentemente ocorre quando: o servidor trava ou reinicia no meio da transferência, um balanceador de carga ou proxy derruba a conexão (timeout de inatividade, requisição muito grande), um firewall encerra conexões de longa duração, o servidor tem um timeout de keep-alive mais curto que o esperado, ou há uma interrupção de rede entre cliente e servidor.
Como corrigir: Tente a requisição novamente — problemas de rede transitórios são a causa mais comum. Use o modo verbose: curl -v URL para ver o ponto exato da falha. Se o erro ocorre durante uploads grandes, tente transferência em chunks: curl -H "Transfer-Encoding: chunked" URL. Para operações Git exibindo RPC failed; curl 56, aumente o buffer: git config http.postBuffer 524288000.

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

Erro 60: Problema com Certificado SSL

O que significa: Seu terminal exibe curl: (60) SSL certificate problem: unable to get local issuer certificate. O curl não conseguiu verificar o certificado SSL do servidor contra seu pacote de CA (Autoridade Certificadora). O handshake TLS foi concluído no nível do protocolo, mas a validação do certificado falhou.
Causas: Causas mais comuns: o servidor usa um certificado autoassinado, o certificado está expirado, a cadeia de certificados está incompleta (faltando certificados intermediários), o pacote de CA do curl está desatualizado (comum em sistemas antigos ou em containers Docker), ou o Common Name / SAN do certificado não corresponde ao hostname solicitado.
Como corrigir: Atualize o pacote de CA: curl --cacert /path/to/cacert.pem URL. Baixe um pacote atualizado em https://curl.se/ca/cacert.pem. Para diagnosticar: openssl s_client -connect api.example.com:443 -showcerts. Para certificados autoassinados em desenvolvimento, use curl -k URL (nunca em produção — isso desativa toda a verificação de certificado). No Docker, instale o pacote ca-certificates.

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

Outros Códigos de Erro

Código de Saída	Nome do Erro	Descrição
0	CURLE_OK	Sucesso. A operação foi concluída sem erros.
1	CURLE_UNSUPPORTED_PROTOCOL	Protocolo não suportado. A URL usa um protocolo que o curl não foi compilado para suportar.
3	CURLE_URL_MALFORMAT	URL malformada. A sintaxe da URL é inválida ou não pôde ser analisada.
5	CURLE_COULDNT_RESOLVE_PROXY	Não foi possível resolver o proxy. O hostname do proxy especificado não pôde ser resolvido.
18	CURLE_PARTIAL_FILE	Arquivo parcial. A transferência foi interrompida e apenas parte do arquivo foi recebida.
23	CURLE_WRITE_ERROR	Erro de escrita. O curl falhou ao gravar dados recebidos no disco (permissão negada ou disco cheio).
37	CURLE_FILE_COULDNT_READ_FILE	Não foi possível ler o arquivo. Um arquivo local referenciado na requisição não pôde ser aberto ou lido.
52	CURLE_GOT_NOTHING	Resposta vazia do servidor. O servidor fechou a conexão sem enviar nenhum dado.
77	CURLE_SSL_CACERT_BADFILE	Problema com certificado CA SSL. Não foi possível ler ou analisar o arquivo de certificado CA especificado.
92	CURLE_HTTP2_STREAM	Erro de stream HTTP/2. Ocorreu um erro de protocolo HTTP/2 no nível do stream durante a transferência.

0CURLE_OK

Sucesso. A operação foi concluída sem erros.

1CURLE_UNSUPPORTED_PROTOCOL

Protocolo não suportado. A URL usa um protocolo que o curl não foi compilado para suportar.

3CURLE_URL_MALFORMAT

URL malformada. A sintaxe da URL é inválida ou não pôde ser analisada.

5CURLE_COULDNT_RESOLVE_PROXY

Não foi possível resolver o proxy. O hostname do proxy especificado não pôde ser resolvido.

18CURLE_PARTIAL_FILE

Arquivo parcial. A transferência foi interrompida e apenas parte do arquivo foi recebida.

23CURLE_WRITE_ERROR

Erro de escrita. O curl falhou ao gravar dados recebidos no disco (permissão negada ou disco cheio).

37CURLE_FILE_COULDNT_READ_FILE

Não foi possível ler o arquivo. Um arquivo local referenciado na requisição não pôde ser aberto ou lido.

52CURLE_GOT_NOTHING

Resposta vazia do servidor. O servidor fechou a conexão sem enviar nenhum dado.

77CURLE_SSL_CACERT_BADFILE

Problema com certificado CA SSL. Não foi possível ler ou analisar o arquivo de certificado CA especificado.

92CURLE_HTTP2_STREAM

Erro de stream HTTP/2. Ocorreu um erro de protocolo HTTP/2 no nível do stream durante a transferência.

Como Depurar Erros do curl

Quando o curl falha, estas três flags ajudam você a identificar rapidamente a causa raiz — desde resolução DNS até handshake SSL e payload de resposta.

1
Ativar saída verbose
Execute curl -v URL para ver o ciclo completo de requisição/resposta: resolução DNS, conexão TCP, handshake TLS, cabeçalhos de requisição enviados e cabeçalhos de resposta recebidos. Esta é a flag de depuração mais útil.
2
Verificar o código de status HTTP
Execute curl -o /dev/null -s -w "%{http_code}" URL para obter apenas o código de status HTTP (200, 404, 500, etc.) sem o corpo da resposta. Útil para verificações rápidas de saúde e scripts.
3
Mostrar erros silenciosamente
Execute curl -sS URL para suprimir a barra de progresso (-s) mas ainda mostrar erros (-S). Perfeito para scripts onde você quer saída limpa mas precisa detectar falhas.

Perguntas Frequentes

Como verificar o código de saída do curl?

Após executar um comando curl, o código de saída é armazenado na variável especial do shell. No Bash/Zsh, execute echo $? imediatamente após o comando curl. No PowerShell, use $LASTEXITCODE. Em scripts, você pode verificá-lo com uma condicional: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. O código de saída 0 significa sucesso; qualquer outro número indica um erro. Para ver tanto o código de status HTTP quanto o código de saída do curl, combine curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?". Note que o código de saída do curl é diferente do código de status HTTP — o curl retorna 0 mesmo para HTTP 404 a menos que você use a flag --fail.

Como corrigir o erro 28 do curl (operação expirou)?

O erro 28 significa que a requisição excedeu o tempo máximo permitido. Primeiro, aumente o timeout: curl --connect-timeout 30 --max-time 120 URL. O --connect-timeout limita a fase de conexão TCP, enquanto --max-time limita a operação inteira. Em seguida, diagnostique o gargalo com curl -v URL — a saída verbose mostra exatamente onde o curl trava (DNS, conexão, TLS ou transferência). Correções comuns: verifique sua conexão de rede e configurações DNS, verifique se o servidor está respondendo (ping e telnet), ignore proxies com --noproxy '*', e para downloads grandes adicione --retry 3 --retry-delay 5 para tentativas automáticas.

Como corrigir erros de certificado SSL do curl (erro 60)?

O erro 60 significa que o curl não consegue verificar o certificado SSL do servidor. A correção depende da causa. Para um pacote de CA desatualizado: baixe um novo em https://curl.se/ca/cacert.pem e use curl --cacert /path/to/cacert.pem URL. Para containers Docker: instale o pacote ca-certificates (apt-get install ca-certificates). Para certificados autoassinados em desenvolvimento: use curl -k URL para pular a verificação — mas nunca use -k em produção pois isso desativa toda a verificação de certificado. Para diagnosticar: execute openssl s_client -connect host:443 -showcerts para inspecionar a cadeia de certificados. Se o certificado expirou ou o hostname não corresponde, o problema está no servidor.

O que significa o erro 7 do curl (falha ao conectar)?

O erro 7 significa que o curl resolveu o hostname para um endereço IP mas não conseguiu estabelecer uma conexão TCP. O servidor ativamente recusou a conexão ou a tentativa de conexão expirou no nível de rede. Causas comuns: o serviço não está em execução no host de destino (verifique com systemctl status ou docker ps), um firewall está bloqueando a porta (teste com telnet host port), você está usando a porta errada (ex.: 80 em vez de 443, ou 8080 para um servidor de desenvolvimento), ou o backlog de escuta do servidor está cheio sob carga pesada. Para depurar: use curl -v URL e procure por "Connected to" ou "Connection refused" na saída.