Taxonomia de falhas A2P SMS: como classificar rejeições, expirações e resultados incertos

Porque um único estado de falha não serve para operar uma rota

Um único estado de «falha» simplifica o relatório, mas elimina a informação necessária para decidir o que fazer em seguida. Não é equivalente uma solicitação SMPP ser rejeitada por um endereço de destino inválido, o SMSC aceitar a mensagem mas esta expirar durante o período de validade, ou o sistema não receber um DLR interpretável.

A taxonomia de falhas A2P SMS deve permitir comparar resultados entre rotas, fornecedores, destinos e janelas temporais sem substituir a evidência técnica original. O seu objetivo não é adivinhar a causa final de cada mensagem, mas organizar os factos observáveis e associar a cada caso uma ação proporcional.

Uma classificação útil responde a quatro perguntas: onde ocorreu o resultado, se é final ou pode evoluir, que evidência o suporta e que ação é permitida. Esta disciplina reduz novas tentativas desnecessárias, evita atribuições incorretas e melhora a qualidade das escaladas técnicas.

• Não utilize «falha» como causa raiz.
• Mantenha separados o resultado da solicitação, o estado de entrega e a causa confirmada.
• Diferencie os estados finais dos estados intermédios.
• Conserve sempre o código e o texto original recebidos, mesmo depois de aplicar um mapeamento interno.

Princípio da evidência: factos observáveis, inferências e causas confirmadas

A primeira regra é separar o facto técnico da sua interpretação. Uma resposta SMPP com command_status de sucesso comprova que a operação de protocolo foi aceite; não confirma que o SMS chegou ao terminal. Da mesma forma, um DLR com estado DELIVERED é uma confirmação recebida através da cadeia de entrega, não uma verificação independente e universal de leitura ou receção física por uma pessoa.

Os DLR podem incluir identificador, data de envio, data de conclusão, estado e código de erro. Estes campos permitem reconstruir um ciclo de vida, desde que o identificador possa ser associado de forma fiável à mensagem original. No entanto, o formato concreto dos receipts transportados em short_message pode variar conforme o gateway ou SMSC, pelo que o parser deve ser controlado por fornecedor ou rota.

A ausência de DLR também não comprova, por si só, uma não entrega. Pode dever-se ao não recebimento do callback, à impossibilidade de interpretar o DLR, a um desfasamento de reconciliação ou a uma política de reporte da cadeia upstream. Deve ser classificada como incerteza até ser obtida evidência adicional.

• Facto observável: resposta HTTP, submit_sm_resp, DLR, callback, consulta de estado ou timeout interno.
• Inferência: «provável congestionamento», «possível restrição de remetente» ou «possível filtragem».
• Causa confirmada: apenas quando um código, uma resposta documentada ou uma investigação do fornecedor a identifica.
• Nível de confiança: registe se a classificação é direta, inferida ou pendente de confirmação.

As cinco famílias operacionais de resultado

Uma taxonomia mínima e comparável pode organizar os desfechos em cinco famílias. Cada família deve conservar o estado original, a origem da evidência e o nível de confiança. As famílias não substituem os códigos do fornecedor: agrupam-nos para fins de operação, análise e decisão.

A mesma rota pode produzir resultados de várias famílias. Por isso, não convém avaliar uma rota com uma única percentagem agregada sem analisar a composição das falhas, a evolução temporal e a evidência disponível.

• Rejeição antes da aceitação: a plataforma local interrompe a tentativa antes de chegar ao SMSC, ou o SMSC rejeita a solicitação. Mantenha ambas as situações diferenciadas. Possíveis exemplos técnicos: falha de bind, credenciais inválidas, endereço de origem inválido ou endereço de destino inválido.
• Falha temporária: a evidência do fornecedor identifica-a expressamente como temporária ou passível de nova tentativa. Não transforme um erro genérico em temporário por conveniência operacional.
• Falha final: existe um resultado negativo final para o qual a documentação ou a evidência disponível não indica uma nova tentativa segura. Uma rejeição do SMSC pode pertencer a esta família quando provavelmente se repetirá com a mesma solicitação.
• Expiração: a mensagem esgotou uma janela de validade antes de a entrega ser concluída. Deve ser separada da falha final porque a duração da validade e o caso de uso são relevantes.
• Resultado incerto: o SMSC pode ter aceite a mensagem, mas não existe um DLR recebido e interpretável que permita encerrá-la como entregue, falhada ou expirada.

Dados que devem ser conservados por mensagem

A classificação será frágil se os registos não permitirem reconstruir a sequência. O identificador interno deve coexistir com os identificadores atribuídos pela plataforma, pelo fornecedor ou pelo SMSC. O DLR deve ser ligado à mensagem original sem depender apenas de um texto de receipt que possa variar entre implementações.

O destino deve ser armazenado num formato internacional normalizado, em conformidade com a estrutura do plano E.164, separado dos atributos utilizados para encaminhar ou segmentar. A normalização não torna um número válido, ativo, consentido ou entregável; apenas melhora a consistência do tratamento de dados e da análise.

Também é importante conservar uma classificação controlada do conteúdo e do remetente, sem utilizar esses campos para inferir uma causa sem evidência. Por exemplo, uma diferença de comportamento por tipo de remetente pode justificar uma investigação, mas não confirma por si só uma restrição de remetente.

• Identificador interno da tentativa e da mensagem lógica.
• Identificadores da plataforma, do fornecedor, do SMSC e do DLR, quando existirem.
• Marcas temporais: criação, aceitação, envio, atualização, receção do DLR e encerramento interno.
• Destino normalizado, país associado e operador apenas quando o dado existir com evidência suficiente.
• Remetente, tipo de remetente e configuração relevante da solicitação.
• Rota, fornecedor, ligação, versão do parser e versão do mapeamento.
• Classe de conteúdo ou caso de uso: OTP, transacional ou marketing legítimo.
• Estado e código originais, texto original, família normalizada, nível de confiança e ação seguinte.

Como mapear HTTP, SMPP e DLR sem perder informação

O mapeamento deve ser uma camada adicional e reversível. Guarde primeiro a resposta original e depois aplique uma regra versionada que produza uma categoria operacional. Não substitua um código SMPP, um estado HTTP ou o texto de um DLR por uma etiqueta interna como «número inválido» ou «filtrado» se essa causa não estiver confirmada.

Em SMPP, command_status informa sobre o sucesso ou falha de uma solicitação SMPP. Códigos como ESME_RINVSRCADR, ESME_RINVDSTADR, ESME_RSYSERR, ESME_RBINDFAIL e ESME_RINVPASWD têm semânticas técnicas distintas e devem permanecer disponíveis para diagnóstico. Uma resposta bem-sucedida a submit_sm não deve ser mapeada como «entregue»: deve ser mapeada, no máximo, como «aceite pela operação de protocolo» ou para um estado intermédio equivalente.

Os estados de entrega também exigem uma hierarquia temporal. ENROUTE é intermédio e pode evoluir, por exemplo, para DELIVERED ou EXPIRED. Um parser não deve encerrar uma mensagem de forma irreversível enquanto apenas dispuser de um estado que possa mudar.

• Capture: protocolo, endpoint ou comando, código, texto, payload original e marca temporal de receção.
• Aplique uma regra com versão, âmbito e data de vigência.
• Defina a precedência entre atualizações: um DLR final válido deve prevalecer sobre um estado intermédio anterior.
• Mantenha os DLR não interpretáveis numa fila de revisão e classifique-os temporariamente como resultado incerto.
• Versione os parsers por fornecedor, ligação ou rota quando o formato do receipt o exigir.
• Evite depender programaticamente de textos variáveis de erros específicos; utilize-os como evidência diagnóstica conservada.

Classificação por acionabilidade

A utilidade de uma taxonomia demonstra-se quando orienta ações seguras. Nem todas as categorias autorizam uma nova tentativa e nem todos os incidentes exigem a interrupção do tráfego. A ação deve depender da família, do código original, do caso de uso, da janela de validade e da evidência acumulada.

As decisões devem ser executadas com regras explícitas. Uma nova tentativa pode ser adequada quando o fornecedor identifica o resultado como temporário ou passível de repetição; não deve ser aplicada automaticamente a rejeições que provavelmente produzirão o mesmo erro com a mesma solicitação. Se houver incerteza, reconcilie primeiro o estado antes de gerar duplicados.

• Corrigir dados ou configuração: aplique a evidências como destino inválido, remetente inválido, erro de bind ou credenciais incorretas. Valide antes de reenviar.
• Tentar novamente em segurança: apenas com evidência de temporalidade ou possibilidade de nova tentativa, uma política de desduplicação e uma janela de validade ainda útil.
• Interromper ou limitar tráfego: perante aumentos sustentados de rejeições técnicas, falhas de autenticação, erros de sistema ou alterações de comportamento que afetem uma rota. A medida deve ser revista com dados, não com uma atribuição automática.
• Escalar para o fornecedor: quando existirem códigos persistentes, DLR inconsistentes, receipts não interpretáveis, discrepâncias de identificadores ou aumento de resultados incertos.
• Manter em observação e reconciliar: para estados intermédios, ausência de DLR dentro da janela definida ou conflitos entre fontes de estado.

Erros ambíguos: quando utilizar «sem causa determinada»

Uma categoria «sem causa determinada» é necessária quando a evidência não permite identificar uma causa concreta. Não é uma falha de análise: é uma forma de impedir que uma hipótese se transforme num dado operacional. Deve ser utilizada, por exemplo, quando é recebido um estado genérico de não entrega sem um código que distinga entre causas possíveis.

Não atribua automaticamente uma não entrega a filtragem de conteúdo, indisponibilidade do terminal, restrição de remetente, congestionamento ou problema de numeração. Um estado negativo pode abranger várias causas. A atribuição deve aguardar um código específico, uma resposta documentada do fornecedor, evidência consistente por segmento ou uma investigação confirmada.

Para que esta categoria seja útil, não deve tornar-se uma gaveta permanente. Cada caso deve conservar metadados suficientes para poder ser reclassificado caso chegue um DLR tardio, o parser seja atualizado ou o fornecedor forneça um esclarecimento.

• Utilize «sem causa determinada» quando faltar evidência discriminante.
• Não utilize esta categoria para ocultar erros de parser, perda de callbacks ou falta de correlação: registe esses problemas separadamente.
• Meça a sua proporção por rota, fornecedor, destino e versão de integração.
• Abra uma revisão se aumentar de forma sustentada ou se se concentrar na mesma rota ou formato de DLR.
• Reclassifique apenas através de uma regra versionada e conserve o histórico da alteração.

Regras diferentes para OTP, transacional e marketing legítimo

A categoria de falha não muda conforme o caso de uso, mas a ação pode mudar. Um OTP tem utilidade limitada no tempo e exige especial cuidado com novas tentativas: enviar um código duplicado ou tardio pode confundir o destinatário e não resolver o acesso. O sistema deve respeitar a validade do código e evitar novas tentativas quando já não acrescentam valor.

As mensagens transacionais podem aceitar uma política de nova tentativa diferente se o seu conteúdo continuar válido e se o evento não for duplicado de forma prejudicial. O marketing legítimo requer uma disciplina ainda maior: só deve ser enviado a destinatários com a base legal e as permissões aplicáveis, e um resultado incerto não deve ser utilizado para justificar reenvios repetidos.

O período de validade faz parte da decisão. A expiração indica que a mensagem permaneceu pendente até esgotar uma janela configurada antes de falhar na plataforma. Por isso, analise as expirações juntamente com a validade configurada e não apenas como um indicador da qualidade da rota.

• OTP: encerramento rápido, desduplicação rigorosa e nova tentativa apenas se ainda estiver dentro da validade do código e se a política o permitir.
• Transacional: valide a idempotência, a validade do evento e o risco de duplicação antes de tentar novamente.
• Marketing legítimo: limite a frequência, respeite o consentimento e as exclusões aplicáveis, e não utilize a incerteza como motivo para insistir.
• Para todos os casos: documente a política de novas tentativas, o número máximo de tentativas e a condição de encerramento.