Timeout e limite de requisição: por que uma API que não responde não é o mesmo que uma API fora do ar

Duas causas diferentes pro mesmo sintoma

Do ponto de vista de quem está chamando, uma API que não responde a tempo e uma API que está genuinamente fora do ar podem parecer a mesma coisa: a chamada falha. Mas a causa por trás é diferente, e tratar as duas situações da mesma forma leva a decisões erradas.

O que é timeout, de fato

Timeout é um limite de tempo definido do lado de quem chama: se a resposta não chegar dentro daquele intervalo, a chamada é interrompida, mesmo que o outro lado ainda estivesse processando e fosse responder logo em seguida. Um timeout configurado curto demais pode interromper chamadas que teriam sucesso, só que um pouco mais lentas que o esperado.

O que é, de fato, estar fora do ar

Indisponibilidade real significa que o servidor da consolidadora não está respondendo de forma nenhuma, por instabilidade, manutenção ou pane. Nesse caso, esperar mais tempo não resolve, porque não existe resposta a caminho.

Por que confundir os dois gera decisão errada

Se o sistema trata todo timeout como indisponibilidade total, ele pode desistir de tentar de novo cedo demais, mesmo quando bastaria esperar um pouco mais ou tentar de novo em poucos segundos. Se trata toda indisponibilidade como simples lentidão, pode insistir repetidamente numa API que não vai responder de jeito nenhum naquele momento, desperdiçando tentativas.

Limite de requisição é outra dimensão do problema

Além do tempo de resposta, muitas APIs impõem um limite de quantas chamadas podem ser feitas num intervalo — ultrapassar esse limite gera erro específico, diferente de timeout ou indisponibilidade, e normalmente exige esperar até o limite ser renovado antes de tentar de novo.

Configurar timeout e retry com esses cenários em mente

Um timeout generoso o suficiente pra não interromper chamada legítima, combinado com uma lógica de nova tentativa que diferencia "demorou mas provavelmente ia responder" de "está genuinamente fora do ar", é o que separa uma integração resiliente de uma que falha com frequência desnecessária.