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

Quando um comando curl falha, devolve um código de saída numérico (também chamado código de erro do curl) que identifica o tipo de erro. 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 na 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 estiver a trabalhar com comandos curl no seu código, cole-os no curl2code para converter para a linguagem de programação à sua escolha.

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. O URL usa um protocolo para o qual o curl não foi compilado com suporte.
3	CURLE_URL_MALFORMAT	URL malformado. A sintaxe do URL é inválida ou não pôde ser analisada.
5	CURLE_COULDNT_RESOLVE_PROXY	Não foi possível resolver o proxy. O nome do host do proxy especificado não pôde ser resolvido.
6	CURLE_COULDNT_RESOLVE_HOST	A pesquisa DNS falhou — não foi possível resolver o nome do host para um endereço IP.
7	CURLE_COULDNT_CONNECT	A conexão TCP falhou — o servidor está inativo, a porta está bloqueada ou a firewall está a rejeitar conexões.
18	CURLE_PARTIAL_FILE	Ficheiro parcial. A transferência foi interrompida e apenas parte do ficheiro foi recebida.
22	CURLE_HTTP_RETURNED_ERROR	O servidor devolveu um erro HTTP (4xx/5xx) e a flag --fail foi usada.
23	CURLE_WRITE_ERROR	Erro de escrita. O curl não conseguiu escrever os 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	O handshake SSL/TLS falhou — incompatibilidade de versão de protocolo ou cipher suite.
37	CURLE_FILE_COULDNT_READ_FILE	Não foi possível ler o ficheiro. Um ficheiro local referenciado no pedido não pôde ser aberto ou lido.
52	CURLE_GOT_NOTHING	Resposta vazia do servidor. O servidor fechou a conexão sem enviar quaisquer dados.
56	CURLE_RECV_ERROR	A conexão foi reiniciada — o servidor terminou a conexão durante a transferência de dados.
60	CURLE_SSL_CACERT	A verificação do 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 ficheiro de certificado CA especificado.
92	CURLE_HTTP2_STREAM	Erro de stream HTTP/2. Ocorreu um erro ao nível do protocolo HTTP/2 durante a transferência.

0CURLE_OK

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

1CURLE_UNSUPPORTED_PROTOCOL

Protocolo não suportado. O URL usa um protocolo para o qual o curl não foi compilado com suporte.

3CURLE_URL_MALFORMAT

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

5CURLE_COULDNT_RESOLVE_PROXY

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

6CURLE_COULDNT_RESOLVE_HOST

A pesquisa DNS falhou — não foi possível resolver o nome do host para um endereço IP.

7CURLE_COULDNT_CONNECT

A conexão TCP falhou — o servidor está inativo, a porta está bloqueada ou a firewall está a rejeitar conexões.

18CURLE_PARTIAL_FILE

Ficheiro parcial. A transferência foi interrompida e apenas parte do ficheiro foi recebida.

22CURLE_HTTP_RETURNED_ERROR

O servidor devolveu um erro HTTP (4xx/5xx) e a flag --fail foi usada.

23CURLE_WRITE_ERROR

Erro de escrita. O curl não conseguiu escrever os 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

O handshake SSL/TLS falhou — incompatibilidade de versão de protocolo ou cipher suite.

37CURLE_FILE_COULDNT_READ_FILE

Não foi possível ler o ficheiro. Um ficheiro local referenciado no pedido não pôde ser aberto ou lido.

52CURLE_GOT_NOTHING

Resposta vazia do servidor. O servidor fechou a conexão sem enviar quaisquer dados.

56CURLE_RECV_ERROR

A conexão foi reiniciada — o servidor terminou a conexão durante a transferência de dados.

60CURLE_SSL_CACERT

A verificação do 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 ficheiro de certificado CA especificado.

92CURLE_HTTP2_STREAM

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

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

O que significa: O seu terminal mostra curl: (6) Could not resolve host. O curl não conseguiu resolver o nome do host para um endereço IP — a pesquisa DNS falhou antes de qualquer tentativa de conexão.
Causas: As causas mais comuns são: um erro de digitação no nome do host (por exemplo, curl https://apiexample.com em vez de api.example.com), problemas no servidor DNS (o DNS configurado está inativo ou inacessível), sem conexão de rede (Wi-Fi desligado, VPN não conectada), ou o domínio genuinamente não existe.
Como corrigir: Primeiro, verifique se o URL está correto. 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 o seu /etc/resolv.conf ou as definições de rede. Se estiver atrás de uma VPN empresarial, 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: O seu terminal mostra curl: (7) Failed to connect to host port: Connection refused. O curl resolveu o nome do host mas não conseguiu estabelecer uma conexão TCP ao servidor — a conexão foi ativamente recusada ou expirou ao nível TCP.
Causas: As causas comuns incluem: o servidor está inativo ou não está em execução, uma firewall está a bloquear a porta (verifique as firewalls locais e do lado do servidor), a porta está errada (por exemplo, o serviço executa na 8080 mas está a conectar à 443), ou o backlog de escuta do servidor está cheio sob carga elevada.
Como corrigir: Verifique se o servidor está em execução: ping api.example.com e telnet api.example.com 443. Verifique se a porta correta está aberta: nmap -p 443 api.example.com. Desative temporariamente a firewall local para testar. Se estiver a usar Docker, certifique-se de que a porta do contentor está publicada. Tente com modo verboso: curl -v https://api.example.com para ver exatamente onde a conexão falha.

$ curl https://localhost:8080/api

Erro 22: HTTP Devolveu Erro

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

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

Erro 28: A Operação Expirou

O que significa: O seu terminal mostra curl: (28) Operation timed out ou curl: (28) Connection timed out. A operação demorou mais do 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: As causas típicas incluem: servidor lento ou sobrecarregado que não responde a tempo, congestionamento de rede ou perda de pacotes, firewall a descartar pacotes silenciosamente (sem rejeição, apenas silêncio), valores de timeout excessivamente restritos definidos com --connect-timeout ou --max-time, ou uma configuração incorreta de proxy a causar atrasos.
Como corrigir: Aumente o timeout: curl --connect-timeout 30 --max-time 120 URL. Use o modo verboso para ver onde fica bloqueado: 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 contorná-lo: curl --noproxy '*' URL. Para transferências de ficheiros 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: O seu terminal mostra 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 da versão TLS (o servidor requer TLS 1.3 mas o seu curl só suporta até TLS 1.2), incompatibilidade de cipher suites, configuração SSL incorreta do servidor (certificado expirado apresentado durante o handshake, cadeia incompleta), o servidor não suporta realmente HTTPS na porta indicada, ou um proxy ou firewall está a interceptar 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, normalmente é o erro 60 — o erro 35 indica tipicamente uma falha de handshake ao nível do protocolo.

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

Erro 56: Falha na Receção — Conexão Foi Reiniciada

O que significa: O seu terminal mostra curl: (56) Recv failure: Connection reset by peer. A conexão foi estabelecida com sucesso, mas a receção de dados falhou — o servidor fechou ou reiniciou a conexão inesperadamente durante a transferência.
Causas: Isto acontece frequentemente quando: o servidor falha ou reinicia durante a transferência, um balanceador de carga ou proxy fecha a conexão (timeout de inatividade, pedido demasiado grande), uma firewall termina conexões de longa duração, o servidor tem um timeout de keep-alive mais curto do que o esperado, ou há uma interrupção de rede entre o cliente e o servidor.
Como corrigir: Tente o pedido novamente — problemas de rede transitórios são a causa mais comum. Use o modo verboso: curl -v URL para ver o ponto exato da falha. Se o erro ocorre durante uploads grandes, tente transferência em blocos: curl -H "Transfer-Encoding: chunked" URL. Para operações Git que mostram 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: O seu terminal mostra curl: (60) SSL certificate problem: unable to get local issuer certificate. O curl não conseguiu verificar o certificado SSL do servidor contra o seu pacote de CA (Autoridade de Certificação). O handshake TLS foi concluído ao nível do protocolo, mas a validação do certificado falhou.
Causas: As causas mais comuns: o servidor usa um certificado autoassinado, o certificado expirou, a cadeia de certificados está incompleta (certificados intermédios em falta), o pacote de CA do curl está desatualizado (comum em sistemas antigos ou em contentores Docker), ou o Common Name / SAN do certificado não corresponde ao nome do host pedido.
Como corrigir: Atualize o pacote de CA: curl --cacert /path/to/cacert.pem URL. Descarregue um pacote atualizado de 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 — desativa toda a verificação de certificados). Em 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. O URL usa um protocolo para o qual o curl não foi compilado com suporte.
3	CURLE_URL_MALFORMAT	URL malformado. A sintaxe do URL é inválida ou não pôde ser analisada.
5	CURLE_COULDNT_RESOLVE_PROXY	Não foi possível resolver o proxy. O nome do host do proxy especificado não pôde ser resolvido.
18	CURLE_PARTIAL_FILE	Ficheiro parcial. A transferência foi interrompida e apenas parte do ficheiro foi recebida.
23	CURLE_WRITE_ERROR	Erro de escrita. O curl não conseguiu escrever os dados recebidos no disco (permissão negada ou disco cheio).
37	CURLE_FILE_COULDNT_READ_FILE	Não foi possível ler o ficheiro. Um ficheiro local referenciado no pedido não pôde ser aberto ou lido.
52	CURLE_GOT_NOTHING	Resposta vazia do servidor. O servidor fechou a conexão sem enviar quaisquer dados.
77	CURLE_SSL_CACERT_BADFILE	Problema com certificado CA SSL. Não foi possível ler ou analisar o ficheiro de certificado CA especificado.
92	CURLE_HTTP2_STREAM	Erro de stream HTTP/2. Ocorreu um erro ao nível do protocolo HTTP/2 durante a transferência.

0CURLE_OK

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

1CURLE_UNSUPPORTED_PROTOCOL

Protocolo não suportado. O URL usa um protocolo para o qual o curl não foi compilado com suporte.

3CURLE_URL_MALFORMAT

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

5CURLE_COULDNT_RESOLVE_PROXY

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

18CURLE_PARTIAL_FILE

Ficheiro parcial. A transferência foi interrompida e apenas parte do ficheiro foi recebida.

23CURLE_WRITE_ERROR

Erro de escrita. O curl não conseguiu escrever os dados recebidos no disco (permissão negada ou disco cheio).

37CURLE_FILE_COULDNT_READ_FILE

Não foi possível ler o ficheiro. Um ficheiro local referenciado no pedido não pôde ser aberto ou lido.

52CURLE_GOT_NOTHING

Resposta vazia do servidor. O servidor fechou a conexão sem enviar quaisquer dados.

77CURLE_SSL_CACERT_BADFILE

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

92CURLE_HTTP2_STREAM

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

Como Depurar Erros do curl

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

1
Ativar saída verbosa
Execute curl -v URL para ver o ciclo completo de pedido/resposta: resolução DNS, conexão TCP, handshake TLS, cabeçalhos do pedido enviados e cabeçalhos da resposta recebidos. Esta é a flag de depuração mais útil.
2
Verificar o código de estado HTTP
Execute curl -o /dev/null -s -w "%{http_code}" URL para obter apenas o código de estado HTTP (200, 404, 500, etc.) sem o corpo da resposta. Útil para verificações rápidas de saúde e scripting.
3
Mostrar erros silenciosamente
Execute curl -sS URL para suprimir a barra de progresso (-s) mas ainda mostrar erros (-S). Perfeito para scripts onde deseja uma saída limpa mas precisa de detetar 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 da shell. Em Bash/Zsh, execute echo $? imediatamente após o comando curl. Em PowerShell, use $LASTEXITCODE. Em scripts, pode verificá-lo com uma condição: 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 estado HTTP como 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 estado HTTP — o curl devolve 0 mesmo para HTTP 404, a menos que use a flag --fail.

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

O erro 28 significa que o pedido 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 toda a operação. Em seguida, diagnostique o gargalo com curl -v URL — a saída verbosa mostra exatamente onde o curl fica bloqueado (DNS, conexão, TLS ou transferência). Correções comuns: verifique a sua conexão de rede e definições DNS, confirme que o servidor está a responder (ping e telnet), contorne 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: descarregue um novo de https://curl.se/ca/cacert.pem e use curl --cacert /path/to/cacert.pem URL. Para contentores Docker: instale o pacote ca-certificates (apt-get install ca-certificates). Para certificados autoassinados em desenvolvimento: use curl -k URL para ignorar a verificação — mas nunca use -k em produção pois desativa toda a verificação de certificados. Para diagnosticar: execute openssl s_client -connect host:443 -showcerts para inspecionar a cadeia de certificados. Se o certificado expirou ou o nome do host não corresponde, o problema está do lado do servidor.

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

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