Uma chamada pode falhar antes de existir qualquer resposta HTTP, na tradução do nome, na conexão ou na negociação TLS. A chamada também pode falhar depois do envio, enquanto o programa espera a resposta. A mensagem de erro indica a etapa, e cada etapa leva a uma investigação diferente.
As etapas de uma chamada HTTPS
Antes de receber a resposta, o programa percorre estas etapas:
- a resolução do nome, em que o DNS traduz o nome do serviço em um endereço IP;
- a conexão TCP, aberta com a porta do serviço;
- a negociação TLS, com a verificação do certificado;
- a troca HTTP, com o envio da requisição e a espera da resposta;
- a interpretação, em que o programa lê o corpo e registra o resultado.
Uma conexão já aberta, guardada pelo programa para reutilização, dispensa as etapas iniciais. Um proxy também muda o caminho, porque o programa conecta ao proxy, e o proxy conecta ao serviço.
O que cada falha indica
- Resolução do nome: mensagens como "host desconhecido", "Could not resolve host" ou o código 11001 do Windows indicam que o nome não foi traduzido. A falha aponta o nome configurado e o DNS usado pela máquina, e não prova a falta de Internet.
- Conexão recusada: mensagens como "a máquina de destino as recusou ativamente", "Connection refused" ou o código 10061 indicam que o destino respondeu recusando a conexão, por falta de serviço na porta ou por um bloqueio que avisa.
- Tempo esgotado na conexão: o código 10060 ou a mensagem "Connection timed out" indicam que a conexão não foi estabelecida no prazo. Endereço errado, rota, firewall que descarta os pacotes e servidor desligado são hipóteses a separar.
- Negociação TLS: mensagens como "não foi possível criar um canal seguro para SSL/TLS" ou "certificate verify failed" indicam uma falha na proteção da conexão. As causas comuns são o certificado vencido, a cadeia não confiável, o nome divergente, o certificado do cliente inacessível, a versão do TLS incompatível e o relógio errado da máquina.
- Tempo esgotado na resposta: o programa enviou a requisição e não recebeu a resposta no prazo. Nesse caso, o serviço pode ter recebido e processado a operação.
- Falha na interpretação: o programa recebeu a resposta, mas não conseguiu ler o corpo ou gravar o resultado. Essa falha não desfaz a operação feita pelo fornecedor.
O texto exato das mensagens varia conforme o sistema operacional e a biblioteca que o programa usa, e o sentido de cada etapa continua o mesmo.
O que o log permite concluir
Uma exceção específica, como a falha na negociação TLS, localiza a tentativa naquela etapa. Uma mensagem genérica de tempo esgotado, sem contexto, não informa se o prazo acabou na conexão, no envio ou na espera da resposta. A ausência de status HTTP no log também tem mais de uma explicação, porque a resposta pode não ter chegado, a leitura pode ter falhado ou o log pode não registrar o status. O significado de cada registro e a tentativa a que ele pertence vêm antes da conclusão.
Prazos diferentes, mensagens parecidas
Um programa pode ter prazos separados para conectar, para receber os dados e para a operação inteira. Um proxy e o próprio servidor também têm os seus prazos. Duas bibliotecas podem mostrar a mesma frase de tempo esgotado para prazos diferentes, e a configuração de uma não vale para a outra.
Um tempo esgotado no programa, ou o cancelamento da espera, não desfaz o processamento no fornecedor. Várias repetições também podem estourar o tempo total disponível, mesmo com cada chamada dentro do próprio prazo. Em uma falha intermitente, a duração de cada tentativa e o intervalo entre elas separam uma espera prevista, uma demora crescente e uma política de repetição inadequada.
No suporte
As verificações partem da máquina que executa a integração, como o caixa 01 ou o servidor geral, e não da máquina em que o erro apareceu. O texto completo da exceção indica a etapa, entre o nome, a conexão, o TLS e a espera da resposta, e as hipóteses ainda não confirmadas ficam registradas como hipóteses.
Para guardar
- O nome, a conexão e o TLS podem falhar antes de qualquer resposta HTTP.
- A conexão recusada indica que o destino respondeu, e o tempo esgotado na conexão indica que nada respondeu no prazo.
- A falha na negociação TLS costuma envolver o certificado, a versão do TLS ou o relógio da máquina.
- A ausência de status no log não localiza sozinha a falha.
- O tempo esgotado à espera da resposta deixa o resultado da operação incerto.
O log mostra uma falha na negociação TLS. Por onde começar a análise?
Pela validade e pela cadeia do certificado do serviço, pelo certificado do cliente quando o serviço exige, pela versão do TLS aceita pelos dois lados e pelo relógio da máquina. A mensagem localiza a etapa, mas ainda não indica qual dessas condições falhou.
Não há status HTTP, e a mensagem informa tempo esgotado à espera da resposta. Isso confirma que a requisição não chegou ao serviço?
Não. O programa não recebeu a resposta no prazo, mas o serviço pode ter recebido e processado a requisição. A situação da operação é consultada pelo procedimento da integração antes de qualquer repetição.