Tratamento de erros da API de rastreamento: como gerenciar números de rastreamento inválidos, limites de taxa e novas tentativas

Trate os erros da API de rastreamento separando entradas inválidas, falhas temporárias, limites de taxa e resultados de status de remessa. Rejeite ou corrija números de rastreamento inválidos em vez de tentar novamente sem alterações, coordene o volume de solicitações quando houver limitação de taxa e repita as tentativas em caso de falhas transitórias com recuo exponencial limitado e jitter. Antes de repetir um registro ou outra solicitação de gravação, determine se a primeira tentativa foi bem-sucedida.

Para desenvolvedores que conectam dados de rastreamento a um sistema de gerenciamento de pedidos, uma plataforma de armazém ou uma página de rastreamento voltada ao cliente, o objetivo não é simplesmente reduzir as solicitações malsucedidas. É garantir uma visibilidade confiável das remessas sem registros duplicados, tempestades de novas tentativas, mensagens de entrega enganosas ou tíquetes de suporte desnecessários.

Classifique a falha antes de escolher uma resposta

Uma integração de rastreamento tem vários resultados distintos a serem avaliados: se a solicitação de rede foi concluída, se a API aceitou a operação, se cada item de rastreamento solicitado foi bem-sucedido e se os eventos da remessa estão disponíveis. Tratar os quatro como um único indicador de sucesso ou falha cria erros evitáveis.

Uma resposta HTTP bem-sucedida não significa necessariamente que todos os itens de um lote foram processados com sucesso. Da mesma forma, uma consulta processada com sucesso, mas sem eventos de rastreamento, não é necessariamente uma falha da API. Analise o corpo da resposta e aplique o significado documentado pelo provedor para cada resultado.

Condição	Ação recomendada	Repetir sem alterações?
Número malformado ou campo de solicitação inválido	Validar e corrigir a entrada	Não
Credenciais ausentes ou inválidas	Verificar credenciais, permissões e ambiente	Não até corrigir
Resposta de limite de taxa	Atrasar o trabalho afetado e reduzir a pressão compartilhada de solicitações	Após a espera necessária, se for seguro
Falha temporária do serviço	Aplicar recuo limitado e verificar a segurança da operação	Geralmente, dentro de um orçamento de novas tentativas
Tempo limite após o envio de um registro	Verificar se o registro existe	Não cegamente
Consulta aceita sem eventos de remessa	Seguir o ciclo de vida de rastreamento documentado	Usar atualização programada, não novas tentativas rápidas

Os códigos de status HTTP fornecem um ponto de partida, não uma árvore de decisão completa específica do provedor. A RFC 9110 define a semântica HTTP, enquanto a RFC 6585 define 429 Too Many Requests. Sua integração também deve interpretar os códigos de erro da aplicação documentados e os resultados por item.

Números de rastreamento inválidos: diferencie entradas incorretas de eventos ausentes

“Número de rastreamento inválido” pode descrever problemas diferentes: um identificador malformado, uma combinação de transportadora e número não compatível, um campo obrigatório de transportadora ausente ou outra falha de validação específica do provedor. Não presuma que um número é inválido apenas porque nenhum evento de rastreamento foi retornado.

Valide sem danificar o identificador

• Armazene os números de rastreamento como strings. O armazenamento numérico pode remover zeros à esquerda ou alterar identificadores longos.
• Preserve a entrada original. Mantenha um valor normalizado separado para que as transformações permaneçam auditáveis.
• Normalize de forma conservadora. Remova espaços em branco ao redor quando apropriado, mas remova caracteres internos ou altere maiúsculas e minúsculas somente quando as regras documentadas permitirem.
• Verifique localmente os campos obrigatórios. Identifique números vazios, identificadores de transportadora ausentes e formatos de solicitação inválidos antes de enviá-los.
• Evite uma expressão regular universal para números de rastreamento. Uma regra criada para uma transportadora pode rejeitar identificadores válidos de outra.
• Confirme o conteúdo do campo. Um número de pedido, uma referência de armazém e um número de rastreamento da transportadora não são intercambiáveis, a menos que o endpoint ofereça suporte explícito a eles.

Se a API rejeitar explicitamente a entrada, encaminhe-a para correção em vez de usar um loop automático de novas tentativas. Inclua um motivo útil, como “identificador da transportadora obrigatório”, em vez de reduzir todo problema de validação a “rastreamento falhou”.

Trate “sem eventos” como um estado separado

Uma remessa pode ter um identificador de rastreamento antes que eventos úteis de movimentação estejam disponíveis. A resposta correta depende do modelo de status documentado pela API e do contexto da remessa. Verifique se o identificador veio do sistema de envio, se a seleção da transportadora está correta e se a resposta indica dados pendentes, e não uma entrada rejeitada.

Use estados internos distintos, como input_rejected, awaiting_events e temporarily_unavailable. Esses são estados de aplicação sugeridos, não valores de API padronizados. Eles ajudam a impedir que uma lacuna temporária de dados se transforme em uma mensagem imprecisa para o cliente.

Gerencie os limites de taxa em toda a integração, não por trabalhador

A RFC 6585 define HTTP 429 como uma resposta de limitação de taxa e permite que ela inclua um cabeçalho Retry-After. A norma não estabelece uma permissão ou um método universal de contagem para APIs de rastreamento. Os limites podem ser documentados por conta, credencial, endpoint ou outro escopo; use as regras reais do provedor.

A RFC 9110 especifica duas formas para Retry-After: um número não negativo de segundos ou uma data HTTP. Analise ambas. Se o valor for uma data, calcule cuidadosamente o tempo de espera restante e considere as diferenças entre relógios. Se estiver ausente ou for inutilizável, aplique sua política de recuo alternativa configurada.

Um trabalhador dormindo de forma independente não é suficiente quando outros trabalhadores continuam usando a mesma permissão. Coloque o controle de taxa no limite compartilhado da credencial ou conta relevante. Um agendador central, um token bucket compartilhado ou um controle distribuído equivalente pode coordenar esse tráfego.

1. Identifique o escopo afetado. Determine a qual endpoint, credencial ou conta o limite se aplica.
2. Respeite a instrução de espera do servidor. Não agende uma nova tentativa antecipada em relação ao valor válido de Retry-After.
3. Adie o trabalho enfileirado afetado. Evite bloquear tráfego não relacionado quando os limites forem realmente independentes.
4. Reduza a simultaneidade ou a frequência das solicitações. Esperar uma vez sem alterar o padrão de solicitações pode recriar o mesmo problema.
5. Retome com espaçamento. Não libere todo o backlog simultaneamente quando o período de espera terminar.

Quando houver suporte, o processamento em lote pode reduzir a quantidade de solicitações, mas deve respeitar as regras documentadas de tamanho e contabilização do lote. Não presuma que um lote consome uma unidade de permissão. Da mesma forma, use webhooks quando disponíveis para reduzir a sondagem evitável, mantendo o processo de reconciliação exigido pela integração.

Use novas tentativas limitadas com recuo e jitter

As novas tentativas são apropriadas quando uma falha pode desaparecer sem alterar a solicitação e repetir a operação é seguro. Falhas temporárias de conexão e determinados erros do servidor podem se enquadrar nessa categoria. Um payload malformado, uma credencial inválida ou um problema permanente de permissão geralmente exige uma correção.

Uma alternativa prática é o recuo exponencial limitado com jitter completo:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Aqui, retry_index começa em zero para a primeira nova tentativa, e um Retry-After ausente não acrescenta nenhum tempo mínimo de espera. Essas são escolhas de implementação, não um algoritmo HTTP obrigatório. Selecione o atraso inicial, o limite, o número máximo de tentativas e o prazo total de acordo com sua carga de trabalho e as orientações do provedor.

O jitter distribui as solicitações ao longo do tempo, em vez de fazer com que todos os trabalhadores as repitam no mesmo horário. O limite de atraso restringe o componente exponencial; ele não deve substituir uma espera mais longa e válida solicitada pelo servidor. Se essa espera exceder o prazo do trabalho, adie ou encerre o trabalho de acordo com a política, em vez de repetir a tentativa antecipadamente.

Dê um ponto final a cada cadeia de novas tentativas

• Limite de tentativas: limite o número de solicitações adicionais.
• Limite de tempo decorrido: pare de repetir trabalhos que excederam sua janela útil de processamento.
• Responsabilidade explícita: escolha qual camada controla as novas tentativas para que as tentativas do cliente HTTP e da fila não se multipliquem inesperadamente.
• Agendamento durável: armazene trabalhos atrasados em vez de depender de longos períodos de espera dentro de processos de curta duração.
• Caminho de recuperação: envie trabalhos esgotados para uma fila de trabalhos com falha que possa ser revisada, incluindo o motivo e a próxima ação.

Durante uma interrupção prolongada, considere um disjuntor que pause temporariamente as chamadas de rotina e permita sondas de recuperação controladas. Esse é um padrão de resiliência da aplicação, não uma evidência de que qualquer provedor de rastreamento específico o exija.

Resolva gravações ambíguas antes de reenviá-las

Um tempo limite informa que sua aplicação não recebeu uma resposta completa. Isso não prova que o servidor rejeitou ou nunca processou a solicitação. Essa distinção é importante ao registrar números de rastreamento ou alterar a configuração de rastreamento.

A RFC 9110 explica os métodos idempotentes e alerta contra a repetição automática de solicitações não idempotentes sem uma base para saber que a repetição é segura ou que a operação original não foi aplicada. Avalie a semântica documentada da operação em vez de presumir que todo endpoint de rastreamento se comporta como uma consulta somente leitura.

• Use um mecanismo de idempotência documentado pelo provedor quando disponível, seguindo suas regras de escopo e retenção.
• Mantenha a mesma chave de idempotência para novas tentativas da mesma operação lógica; não presuma que um cabeçalho personalizado arbitrário será aceito.
• Se houver suporte, verifique o registro existente antes de repetir uma gravação ambígua.
• Use uma restrição de exclusividade local alinhada à identidade de remessa documentada pelo provedor.
• Armazene o resultado da operação para que uma reentrega da fila não acione automaticamente outra gravação.

Para operações em lote, mantenha o resultado de cada item. Repita somente os itens classificados como falhas transitórias e reconcilie os itens cujos resultados continuarem desconhecidos. Reexecutar o lote inteiro pode repetir trabalhos bem-sucedidos e consumir a permissão de solicitações desnecessariamente.

Aplique a política ao seu provedor de rastreamento

Para uma integração com a 17TRACK, use a página da Tracking API e a documentação oficial da API como pontos de partida para o contrato específico do provedor. Mantenha seu classificador de erros configurável em vez de codificar premissas fixas de um guia HTTP genérico.

Antes da implementação, confirme o esquema de solicitação do endpoint relevante, o envelope de resposta, os significados dos erros por item, o escopo do limite de taxa, as restrições de lote e as regras para envios duplicados. Quando usar entrega de eventos, verifique também os requisitos de confirmação, autenticação e reentrega. Este guia não prescreve um limite de taxa numérico da 17TRACK, uma programação de novas tentativas ou um recurso de idempotência.

Registre cada regra confirmada em um mapeamento da resposta do provedor para a ação da aplicação: corrigir a entrada, reparar a configuração, aguardar, reconciliar ou escalar. Um erro não reconhecido deve preservar o contexto de diagnóstico e seguir um caminho alternativo limitado, não assumir novas tentativas ilimitadas.

Monitore a qualidade da recuperação e teste os caminhos de falha

Registre a operação, o endpoint, o status HTTP, o código de erro da aplicação, o número da tentativa, a latência, a próxima ação agendada e o identificador da solicitação do provedor quando fornecido. Evite registrar chaves de API, informações de endereço desnecessárias ou corpos de resposta irrestritos. Mascare ou faça hash dos identificadores de rastreamento quando os valores completos não forem necessários.

Acompanhe separadamente as taxas de entradas inválidas, limitação de taxa, idade da fila, novas tentativas esgotadas e a última sincronização bem-sucedida. Uma integração pode ter uma baixa taxa de erros HTTP e ainda fornecer informações desatualizadas sobre as remessas. As páginas voltadas ao cliente devem preservar o último status de remessa conhecido e distinguir uma falha de atualização de uma exceção de entrega informada pela transportadora.

Antes do lançamento, teste entradas malformadas, identificadores válidos sem eventos, ambas as formas de Retry-After, cabeçalhos ausentes, falhas parciais de lote, tempos limite após gravações e reentrega da fila. Simule também uma interrupção longa o suficiente para esgotar o orçamento de novas tentativas. O teste só passa quando o trabalho é interrompido ou adiado de forma previsível, os itens bem-sucedidos não são repetidos desnecessariamente e os itens com falha permanecem recuperáveis.

FAQ

Um número de rastreamento inválido deve ser repetido automaticamente?

Não quando a API rejeita explicitamente a entrada como inválida. Corrija primeiro o número, a seleção da transportadora ou os campos obrigatórios. Se a resposta significar que os eventos da remessa ainda não estão disponíveis, use o fluxo de atualização documentado em vez de tratá-la como uma falha de validação.

HTTP 200 significa que uma solicitação em lote foi totalmente bem-sucedida?

Não necessariamente. Verifique o esquema de resposta do provedor para obter os resultados no nível da operação e do item. Persista os sucessos e isole as falhas para que repetir um item não repita desnecessariamente os demais.

Quantas tentativas uma integração de rastreamento deve permitir?

Não existe uma quantidade universal. Defina um limite de tentativas e um orçamento de tempo decorrido com base nas orientações do provedor, na segurança da operação e no período em que o resultado continua útil. Uma sincronização em segundo plano programada pode tolerar uma janela de recuperação diferente da de uma solicitação interativa do cliente.

Um tempo limite deve marcar imediatamente uma remessa como falha?

Não. O tempo limite de uma solicitação é um resultado da integração, não um evento da remessa. Preserve o último estado de rastreamento conhecido, agende uma recuperação segura e evite transformar um problema de conectividade em uma notificação de falha na entrega.

O que deve acontecer quando as novas tentativas se esgotarem?

Mova o trabalho para uma fila durável de trabalhos com falha ou de revisão, mantendo seu contexto de diagnóstico. Identifique se a recuperação exige uma entrada corrigida, credenciais restauradas, assistência do provedor ou uma repetição controlada posterior. Não o descarte silenciosamente nem reinicie o mesmo ciclo ilimitado de novas tentativas.

Fontes

• RFC 9110: Semântica HTTP — semântica dos status HTTP, métodos idempotentes, considerações sobre novas tentativas automáticas e o campo Retry-After.
• RFC 6585: Códigos de status HTTP adicionais — definição de 429 Too Many Requests e seu cabeçalho Retry-After opcional.
• Tracking API da 17TRACK — ponto de entrada oficial para o produto de API de rastreamento.
• Documentação da API da 17TRACK — referência para verificar os requisitos de integração específicos do provedor.