Skip to main content
HomeBlogGuiasA solicitação de rastreamento em tempo real expirou? Regras de nova tentativa, fallback e status a seguir

A solicitação de rastreamento em tempo real expirou? Regras de nova tentativa, fallback e status a seguir

17TRACK

Quando uma solicitação de rastreamento em tempo real sofre timeout, trate o status mais recente da remessa como desconhecido — não como atrasado, perdido ou inalterado. Tente novamente apenas dentro de um limite de tempo definido e, em seguida, mostre uma atualização do último estado conhecido claramente identificada ou peça ao usuário que tente novamente mais tarde. Mantenha separados, durante todo o processo, o resultado da solicitação, a atualidade dos dados e o status real da encomenda.

Solicitação de rastreamento em tempo real expirou: nova tentativa, fallback e status

Essa distinção é importante tanto para páginas de rastreamento voltadas aos clientes quanto para sistemas que usam dados de rastreamento para acionar notificações ou fluxos de suporte. Um timeout informa que uma resposta não chegou a tempo. Ele não informa se a transportadora tem um novo evento, se um serviço upstream processou a solicitação ou se a encomenda se movimentou.

Primeiro, identifique o que sofreu timeout

Uma solicitação de rastreamento pode falhar em vários pontos: o navegador pode parar de esperar pela sua aplicação, a sua aplicação pode parar de esperar por uma API de rastreamento ou essa API pode sofrer timeout ao entrar em contato com outro serviço. O usuário pode ver o mesmo erro genérico em cada caso, mas a ação adequada será diferente.

  • Timeout no lado do cliente: O aplicativo parou de esperar. A solicitação no lado do servidor ainda pode ter sido concluída. Verifique seus próprios registros de solicitações ou o armazenamento de resultados antes de emitir outra solicitação que possa duplicar o trabalho.
  • Falha de rede ou conexão: Seu sistema não recebeu uma resposta utilizável. Talvez você não saiba se o serviço remoto processou a solicitação.
  • HTTP 504: Um gateway ou proxy não recebeu uma resposta oportuna de um servidor upstream. Isso descreve o caminho da solicitação, não a remessa.
  • HTTP 408: O servidor não recebeu uma mensagem de solicitação completa dentro do tempo que estava preparado para esperar. Esse não é um status de rastreamento da transportadora.
  • HTTP 200 com um evento antigo: A solicitação foi bem-sucedida, mas as informações de rastreamento retornadas ainda podem estar desatualizadas. Uma resposta HTTP bem-sucedida não garante a atualidade dos dados.

Registre esses resultados como diagnósticos da solicitação. Não traduza nenhum deles em rótulos da remessa, como “em trânsito”, “exceção” ou “entregue”. Esses rótulos devem vir de eventos de rastreamento ou de um campo de status documentado, não da camada de transporte.

Use uma nova tentativa limitada, não um loop sem fim

Para uma consulta de rastreamento somente leitura, uma nova tentativa após um timeout costuma ser razoável. Ainda assim, ela deve ser limitada. Solicitações repetidas podem aumentar a carga sobre um serviço com problemas, prolongar a espera do usuário e criar trabalho duplicado quando várias camadas da aplicação tentam novamente de forma independente.

  1. Defina um prazo total. Decida quanto tempo a operação voltada ao usuário pode durar, incluindo a tentativa inicial e qualquer nova tentativa. Não dê a cada tentativa um prazo completo novo que ultrapasse o tempo que o solicitante pode esperar.
  2. Verifique se a operação é segura para repetir. Uma consulta normalmente difere de uma solicitação que registra uma remessa, altera configurações ou cria um recurso. Não reproduza automaticamente uma solicitação que altera o estado, a menos que o contrato do provedor ou seus controles de idempotência tornem isso seguro.
  3. Tente novamente uma falha transitória com moderação. Use um orçamento pequeno e explícito de novas tentativas e um atraso com jitter, em vez de enviar novas tentativas imediatas e simultâneas de muitos clientes.
  4. Respeite as instruções aplicáveis do servidor. Se uma resposta incluir um cabeçalho Retry-After válido, não programe uma nova tentativa anterior. Respeite também qualquer limite mais rigoroso da aplicação ou específico do provedor.
  5. Pare quando o prazo ou o orçamento se esgotar. Mude para uma resposta de fallback e agende separadamente uma reconciliação posterior, se o seu fluxo de trabalho precisar dela.

Um design prático pode permitir uma nova tentativa voltada ao usuário se ainda houver tempo suficiente, transferindo novas tentativas para uma atualização em segundo plano. Esse é um exemplo de política, não uma regra universal de API. Escolha os limites com base nas metas do seu nível de serviço, na latência observada e na documentação do provedor. Conte também as novas tentativas feitas por bibliotecas HTTP, gateways e workers de tarefas; caso contrário, uma política aparentemente moderada da aplicação poderá gerar muitas chamadas upstream.

Para HTTP 429, trate a resposta como um sinal de limite de taxa, não como motivo para tentar novamente imediatamente. HTTP 503 pode indicar uma incapacidade temporária de processar a solicitação, e um servidor pode fornecer Retry-After. Um 504 pode ser transitório, mas não garante que a próxima tentativa funcionará. Erros de autenticação geralmente exigem verificações de credenciais ou permissões, enquanto solicitações malformadas exigem correção dos dados de entrada. Um identificador de rastreamento que produz um resultado “não encontrado” requer mais cuidado: dependendo do comportamento documentado do provedor e da etapa da remessa, pode ser cedo demais para encontrar um registro ou o identificador pode estar errado. Não transforme um único resultado desse tipo em uma afirmação definitiva de que a encomenda não existe.

Escolha um fallback que preserve o que você sabe

O fallback mais seguro geralmente é o último resultado de rastreamento verificado, acompanhado do horário do próprio evento e de uma indicação honesta de atualidade. Mantenha esse resultado separado da falha da solicitação atual. Uma página poderia dizer: “Última atualização disponível: Saiu da unidade. Última verificação: [horário]. Uma atualização mais recente está temporariamente indisponível.” Inclua “Última verificação” somente se o seu sistema realmente registrar esse dado; ele não substitui o horário do evento da transportadora.

Use o horário mais específico que puder comprovar. O horário de um evento da transportadora descreve quando o evento supostamente ocorreu. O horário em que seu sistema recebeu esse evento descreve a ingestão. O horário em que um usuário abriu a página não descreve nenhum dos dois. Se a fonte não fornecer um horário ou fuso horário de evento confiável, evite inventar um. Da mesma forma, se o resultado armazenado em cache não tiver um horário de recuperação registrado, chame-o de “última atualização disponível”, em vez de afirmar que foi atualizado recentemente.

Um fallback deve respeitar três limites:

  • Mostre dados armazenados em cache como dados armazenados em cache. Não apresente um evento antigo como resultado da solicitação que sofreu timeout.
  • Não deduza progresso com base no tempo decorrido. Uma encomenda não está “saiu para entrega” apenas porque está em trânsito há vários dias.
  • Não esconda incertezas relevantes. Se não houver um resultado anterior, diga que o rastreamento está temporariamente indisponível, em vez de exibir um status padrão fabricado.

Outras rotas de fallback podem incluir um armazenamento de rastreamento sincronizado anteriormente, uma consulta autorizada à transportadora ou uma atualização posterior em segundo plano. Use-as somente se forem compatíveis com a remessa, suas permissões e os termos da fonte de dados. Uma segunda fonte pode ter nomes de eventos ou atrasos de relatório diferentes; portanto, preserve a procedência e evite combinar registros conflitantes sem uma regra para isso. Se um cliente puder agir com base no resultado, ofereça uma forma de tentar novamente ou entrar em contato com o suporte, em vez de deixar um indicador de carregamento indefinidamente.

Mantenha separados o status da solicitação, a atualidade dos dados e o status da remessa

Esses são três campos diferentes, mesmo que uma interface os exiba juntos. O status da solicitação informa se a consulta foi bem-sucedida, sofreu timeout ou recebeu um erro. A atualidade dos dados informa quando as informações retornadas ou armazenadas foram observadas. O status da remessa informa o que a fonte de rastreamento relata sobre a encomenda. Separá-los evita que uma falha temporária da API substitua um evento de entrega válido ou transforme um evento antigo de trânsito em uma afirmação atual.

Por exemplo, um sistema pode manter um evento “Entregue” verificado de uma consulta anterior enquanto a atualização atual sofre timeout. O evento de entrega não desaparece. O estado combinado correto é que o último status disponível da remessa é entregue e que a atualização mais recente falhou. Por outro lado, se o último evento for “Em trânsito”, um timeout não confirma que a encomenda continua em trânsito neste momento; ele confirma apenas que nenhuma resposta mais recente foi obtida.

Aplique uma regra definida quando os eventos chegarem fora de ordem. Compare identificadores de eventos, registros de data e hora, fonte e a semântica de status documentada pelo provedor, quando disponível. Não presuma que a ordem em que seu sistema recebeu as atualizações seja a ordem em que os eventos da remessa ocorreram. Da mesma forma, um evento antigo recebido tardiamente não deve substituir automaticamente um status mais recente verificado. Correções e exceções podem ser legítimas; portanto, evite uma regra geral que trate mudanças de status após a entrega como impossíveis. Preserve os eventos subjacentes e investigue contradições, em vez de reescrever o histórico silenciosamente.

Se um provedor retornar HTTP 202, interprete-o de acordo com o contrato desse endpoint: a aceitação de uma solicitação, por si só, não significa que a consulta de rastreamento foi concluída. Da mesma forma, HTTP 200 estabelece que uma solicitação HTTP foi bem-sucedida segundo a semântica desse endpoint; ele não prova que todos os campos de rastreamento estejam presentes ou atuais. Mapeie campos de resposta específicos do provedor somente depois de verificar a documentação do provedor.

Torne a falha visível para os operadores sem alarmar os clientes

Um registro operacional útil inclui o ID da solicitação, o endpoint ou a operação, a quantidade de tentativas, o tempo decorrido, a camada que sofreu timeout, o status HTTP, caso tenha sido recebido, e se a resposta veio de uma consulta ao vivo ou de um fallback. Para dados de rastreamento, registre a fonte e os horários relevantes do evento ou da recuperação. Trate números de rastreamento e informações de clientes de acordo com as regras de acesso e retenção da sua organização; a utilidade para diagnóstico não é motivo para expor identificadores completos em registros sem restrições.

Observe padrões em vez de depender de um único timeout. Uma taxa crescente de timeouts em uma rota de determinada transportadora, respostas 429 repetidas ou uma diferença cada vez maior entre o horário do evento da transportadora e o horário de recuperação podem indicar problemas diferentes. O primeiro pode exigir uma investigação com o provedor, o segundo pode exigir controle de taxa e o terceiro pode exigir a verificação da sincronização ou da entrega de eventos. Se uma aplicação oferecer rastreamento por meio de um provedor como a API de rastreamento 17TRACK, use a documentação desse provedor para verificar os campos de resposta específicos do endpoint, os limites de solicitações e o tratamento de erros antes de implementar essas regras gerais.

Para a mensagem voltada ao cliente, seja preciso e moderado: “Não foi possível atualizar o rastreamento no momento. Esta é a última atualização disponível.” Forneça uma próxima etapa quando isso ajudar, como tentar novamente mais tarde ou entrar em contato com o suporte caso a remessa esteja além do prazo de entrega esperado informado pelo vendedor ou pela transportadora. Evite prometer um horário de atualização que seu sistema não possa garantir.

Lista de verificação para publicar um fluxo de rastreamento seguro contra timeouts

  • Confirme qual camada impõe cada timeout e qual camada é responsável pelas novas tentativas.
  • Defina um prazo total para a solicitação e um orçamento separado e limitado para novas tentativas.
  • Verifique se as operações repetidas automaticamente são seguras para repetir.
  • Respeite os limites de taxa e as instruções válidas de Retry-After.
  • Armazene o resultado da solicitação separadamente do status da remessa e do histórico de eventos.
  • Identifique os dados de fallback e mantenha sua fonte e seus horários quando disponíveis.
  • Teste cenários sem cache, com cache desatualizado, 429, 503, 504 e respostas tardias.
  • Verifique se um timeout não pode acionar uma notificação incorreta de entrega nem apagar um evento verificado.

A regra principal é simples: tente novamente uma solicitação somente quando isso for seguro e útil; use fallback apenas para informações que você consiga identificar; e nunca faça uma afirmação sobre o status da remessa com base em um timeout HTTP.

Perguntas frequentes

Devo tentar novamente imediatamente uma solicitação de rastreamento que sofreu timeout?

Não automaticamente. Verifique se a operação é segura para repetir, se o prazo geral deixa tempo para outra tentativa e se nenhuma instrução de limite de taxa determina que é preciso esperar. Uma nova tentativa curta e limitada, com jitter, pode ser adequada para uma consulta somente leitura; novas tentativas imediatas e repetidas são uma opção padrão ruim.

HTTP 504 significa que o sistema de rastreamento da transportadora está fora do ar?

Não. Significa que um gateway ou proxy não recebeu uma resposta upstream oportuna. O problema pode estar em qualquer ponto desse caminho de solicitação. Isso não estabelece a disponibilidade geral da transportadora nem a condição da encomenda.

Posso mostrar o último status conhecido após um timeout?

Sim, se você identificá-lo como a informação mais recente disponível, e não como uma atualização ao vivo bem-sucedida. Mostre o horário do evento e o horário de recuperação quando forem conhecidos e deixe claro que não foi possível confirmar uma atualização mais recente.

Um timeout deve alterar uma remessa de “em trânsito” para “exceção”?

Não. Um timeout é uma falha da solicitação, não um evento da remessa. Altere o status da remessa somente quando uma fonte de rastreamento confiável fornecer um evento ou status que justifique a mudança.

E se a solicitação que sofreu timeout estivesse criando ou registrando um registro de rastreamento?

Não presuma que ela falhou. O sistema remoto pode tê-la processado antes que a resposta fosse perdida. Verifique se já existe um resultado e use um mecanismo de idempotência documentado ou um procedimento de recuperação aprovado pelo provedor antes de enviá-la novamente.

Fontes