Uma integração que espera indefinidamente pode bloquear uma compra, uma reserva ou uma tarefa interna. Mas definir um prazo curto demais também pode interromper operações válidas. Por isso, como definir timeouts em integrações não é apenas uma decisão de configuração: é preciso acordar quanto o negócio pode esperar, que experiência a pessoa usuária terá e como os resultados incertos serão tratados.
Um timeout limita por quanto tempo um componente espera por uma resposta. Ele não prova que o sistema externo interrompeu o trabalho nem que a operação falhou. Projetar esses limites adequadamente significa decidir o que esperar, quando parar de esperar e o que fazer em seguida.
O prazo deve atender a uma necessidade do negócio
Comece identificando qual processo depende da resposta externa e quais são as consequências da demora. Uma autorização necessária antes de confirmar uma compra não tem a mesma margem de tempo que uma atualização de catálogo que pode ser concluída em segundo plano. O critério não deve ser «qual valor costuma ser usado», mas por quanto tempo o processo pode esperar sem prejudicar a pessoa usuária, a operação ou a consistência dos dados.
Para cada dependência, esclareça:
- Qual decisão está bloqueada: por exemplo, confirmar uma reserva ou mostrar um resultado.
- Quem está esperando: uma pessoa em uma tela, uma API consumidora, um processo noturno ou uma equipe operacional.
- O que acontece se não houver resposta a tempo: é possível adiar, continuar com informações parciais ou interromper o processo?
- O que significa «concluído»: que uma resposta foi recebida, que o fornecedor aceitou a solicitação ou que o efeito final foi confirmado?
Essa última distinção evita confundir uma resposta técnica com o resultado funcional. Um serviço pode aceitar uma solicitação sem ter concluído a operação. Se o negócio precisa conhecer o resultado final, talvez seja melhor consultar o status ou receber uma notificação posterior, em vez de aumentar indefinidamente o tempo de espera.
Separe os limites de conexão, resposta e operação
Um único timeout pode ocultar em que etapa a demora está se acumulando. É recomendável distinguir os limites conforme o ponto de espera e definir uma duração máxima total para a operação. Por exemplo, a tentativa de estabelecer uma conexão pode ter um limite; a espera por dados depois da conexão, outro; e toda a sequência — incluindo chamadas dependentes — deve caber em um orçamento global.
Se houver vários serviços em sequência, o tempo disponível precisa ser distribuído entre eles. Não é razoável que cada dependência consuma, separadamente, o máximo permitido para a pessoa usuária: a soma pode ultrapassar o prazo do processo. Propague um prazo-limite comum, ou deadline, e faça cada componente usar apenas o tempo restante. Assim, uma chamada atrasada não continua trabalhando quando a operação que a originou já perdeu sua utilidade.
Os nomes e o comportamento dos limites variam entre bibliotecas e plataformas. Verifique se o valor configurado se aplica apenas à conexão, à leitura de uma resposta, a cada tentativa ou à operação completa. Confira também se há proxies, balanceadores de carga ou clientes intermediários com limites próprios; na prática, o prazo efetivo costuma ser o mais restritivo do percurso.
O contexto importa. Uma interação com uma pessoa usuária normalmente exige uma resposta rápida ou uma transição clara para um estado pendente. Um processo em lote pode aceitar uma janela maior, desde que tenha supervisão e limites. Nos dois casos, defina o prazo com base nos objetivos do processo e nos dados de latência observados, não em um valor arbitrário.
Quando o prazo terminar, escolha entre cancelar, aguardar ou operar com limitações
O timeout deve acionar uma decisão prevista, não uma exceção sem tratamento. Há três padrões comuns, que podem ser combinados conforme a operação:
- Cancelar e parar de esperar: útil quando a resposta já não oferece valor. Propague o cancelamento para as tarefas em andamento se o cliente e o serviço permitirem, e libere os recursos locais.
- Manter a operação pendente: adequado quando o fornecedor pode processar o trabalho de forma assíncrona. Retorne ou registre uma referência de acompanhamento e permita consultar o status posteriormente.
- Continuar com funcionalidade reduzida: válido quando há uma alternativa segura, como mostrar dados recentes ou adiar uma atualização. Informe qual parte não pôde ser concluída e não apresente informações provisórias como confirmadas.
Cancelar a espera não equivale a desfazer a operação remota. Uma solicitação pode ter chegado ao fornecedor pouco antes de o cliente atingir o limite do prazo. O servidor pode continuar processando-a mesmo que a conexão seja encerrada. Por isso, não marque automaticamente a ação como falha nem confirme à pessoa usuária que nada aconteceu sem evidências suficientes.
Se o efeito não puder permanecer em um estado incerto, projete uma forma de consultar, conciliar ou compensar a operação. O cancelamento efetivo depende dos recursos do sistema remoto e do tipo de trabalho; isso precisa ser verificado, não presumido.
Trate o resultado desconhecido como um estado próprio
Quando o prazo termina sem resposta, o resultado pode ser «desconhecido»: não se sabe se o fornecedor recebeu a solicitação, se a executou ou se houve uma falha antes disso. Separar esse estado de «falhou» e «concluído» ajuda a evitar decisões arriscadas, especialmente em pagamentos, reservas, envios ou alterações de conta.
Antes de tentar novamente uma ação com efeitos, verifique se o contrato da integração oferece suporte a uma chave de idempotência ou a um mecanismo de consulta por identificador. A idempotência pode evitar que uma repetição produza efeitos duplicados, mas somente se estiver implementada e garantida para aquela operação. Se essa proteção não existir, consulte o status ou encaminhe o caso para uma análise controlada antes de repetir.
As novas tentativas também consomem tempo. Inclua-as no limite total e evite que cada tentativa inicie uma espera completa e independente. Uma nova tentativa sem orçamento, com pausas mal ajustadas ou multiplicada por vários componentes pode aumentar a carga justamente quando o serviço está degradado. Para tarefas que não exigem resposta imediata, uma fila e um fluxo de acompanhamento podem ser mais adequados do que manter uma conexão aberta.
Comunique o status e ofereça uma forma clara de recuperação
A mensagem deve refletir o nível de certeza disponível. Se a operação continua em andamento, informe que está pendente; se o resultado é desconhecido, não a apresente como falha nem como sucesso. Explique o que a pessoa pode fazer: aguardar, consultar novamente ou entrar em contato com o suporte. Evite pedir que ela repita uma ação com consequências importantes sem alertar sobre o risco de duplicação.
As equipes internas precisam do mesmo contexto. Registre identificadores de correlação, a dependência, a duração, a etapa em que ocorreu o timeout e o resultado observado. Diferencie os limites de conexão dos limites de resposta ou do prazo total. Não inclua dados sensíveis em registros sem necessidade. Com essas informações, o suporte pode investigar um caso e a equipe técnica pode localizar qual etapa consumiu o orçamento.
Teste e revise os limites com sinais operacionais
Um limite não está validado apenas porque a integração funciona em condições normais. Teste respostas lentas, conexões interrompidas, cancelamentos, erros intermitentes e respostas que chegam depois do vencimento do prazo. Verifique tanto a experiência da pessoa usuária quanto os efeitos no fornecedor e o estado final registrado pelo seu sistema.
Observe a distribuição das latências, a frequência dos timeouts, as operações pendentes e desconhecidas, as novas tentativas e os incidentes por dependência. Um aumento de timeouts pode indicar um limite restritivo demais, mas também uma degradação real do fornecedor, uma sobrecarga local ou um problema no percurso da rede. Não aumente o timeout automaticamente: primeiro identifique onde a demora começa e quais processos estão expostos.
Documente, para cada integração, o prazo por etapa, o orçamento total, a ação quando o limite é atingido, a política de novas tentativas e o mecanismo de recuperação. Revise esses acordos quando o fluxo de negócio ou a latência observada mudar. Um bom timeout não é o mais longo nem o mais curto: é aquele que protege o processo, deixa o status claro e permite a recuperação sem efeitos duplicados.