Mensagens de erro de conexão

Toda vez que uma conexão falha (test connection, envio ao destino, polling), o Lefia traduz o erro técnico bruto em mensagem acionável.

O que cada erro quer dizer

HTTP 4xx — problema seu (não há retry automático)

• 400 Bad Request: payload ou headers inválidos. Verifique o que mandou.
• 401 Unauthorized: credenciais erradas. API Key / Basic Auth / Bearer / OAuth.
• 403 Forbidden: conta sem permissão pra esse recurso, ou IP bloqueado por whitelist.
• 404 Not Found: endpoint não existe. Verifique URL/path.

HTTP 5xx — problema do provider (retry automático)

• 500 Internal Server Error: erro genérico do provider. Não é configuração sua.
• 502 Bad Gateway: proxy / load balancer / CDN com problema. Verifique a status page do provider.
• 503 Service Unavailable: manutenção ou sobrecarga. Verifique status page. Lefia honra Retry-After.
• 504 Gateway Timeout: backend demorou demais. Reduza payload ou tente em horário de menor carga.
• 520-524 Cloudflare: origem do provider com problema. Retry automático.

Network / DNS / TLS

• ECONNREFUSED: servidor recusou conexão. Verifique porta e se está rodando.
• ENOTFOUND: DNS não resolveu. Domínio errado ou inacessível.
• ETIMEDOUT: timeout TCP. Verifique firewall e conectividade.
• EHOSTUNREACH / ENETUNREACH: rota de rede não chega — VPN, firewall.
• Cert expired: certificado TLS expirou. Avise o operador do destino.

SSH/SFTP, FTP, Kafka — específicos

• Authentication failed (SSH): username/senha/chave errados.
• Handshake failed (SSH): cipher/key exchange incompatível.
• 530 Login (FTP): usuário/senha FTP errados.
• 550 (FTP): arquivo/diretório não existe.
• Broker disconnected (Kafka): cluster indisponível.
• SASL authentication failed (Kafka): credenciais SASL erradas.

Retry automático

O Lefia retentar automaticamente em:

• HTTP 408, 429, 5xx (com backoff)
• Network errors (ECONNRESET, ETIMEDOUT, EAI_AGAIN, EPIPE, AbortError)

Não retenta em:

• HTTP 4xx (exceto 408 e 429)
• Cert expirado, auth failed (manual fix necessário)
• 507 Insufficient Storage (operador do destino precisa agir)

Retry-After

Quando provider manda header Retry-After, a mensagem inclui o intervalo sugerido ("Provider pede aguardar 30s antes de retry"). Lefia respeita.

Teste de conexão de destino (modo alcançabilidade)

O botão Testar faz um GET no endereço da conexão. Um destino costuma ser POST-only, então um GET pode devolver 404/405 mesmo com tudo certo. Por isso, para conexões de destino, o teste roda em "modo alcançabilidade": qualquer resposta do servidor conta como alcançável (verde) e a validação real do payload acontece no envio. Só 401/403 (auth) e erros de rede/timeout/DNS reprovam o destino. A origem continua exigindo 2xx (precisa devolver dados via GET).

Tickets relacionados

• #206 implementação base (humanização 5xx + Retry-After + connectors específicos).
• #671 modo alcançabilidade no teste de destino.