Códigos de erro SMPP em SMS A2P: guia operacional para tentativas, correções e encerramentos

O que uma resposta a submit_sm confirma — e o que não confirma

Uma resposta submit_sm_resp confirma o resultado de uma solicitação no protocolo SMPP. O campo command_status da PDU de resposta indica se o SMSC aceitou ou rejeitou essa solicitação SMPP e, quando aplicável, devolve um código de erro.

Uma aceitação técnica não equivale à entrega no dispositivo. Se command_status indicar sucesso e o SMSC devolver um message_id, a mensagem foi aceite por esse sistema para processamento posterior. Isto não demonstra, por si só, que a mensagem tenha chegado à rede móvel, sido entregue ao dispositivo ou vista pelo utilizador.

A primeira regra operacional é separar a aceitação da apresentação da evidência posterior de estado. Guarde o message_id devolvido pelo SMSC juntamente com o identificador interno da mensagem, o destino, a rota ou ligação utilizada, a marca temporal e os parâmetros relevantes da PDU. Esta correlação será necessária para interpretar DLR, query_sm, cancel_sm ou replace_sm.

• submit_sm_resp com sucesso: a solicitação SMPP foi aceite pelo SMSC.
• submit_sm_resp com erro: a solicitação falhou nessa etapa e deve ser classificada antes de voltar a enviar.
• DLR ou consulta de estado: fornecem informação posterior, mas não devem ser confundidos com uma prova independente de receção no dispositivo.
• message_id: referência técnica para operações SMPP posteriores e para correlação de eventos.

As camadas de estado no SMPP: sessão, aceitação do submit, DLR e evidência de receção

Uma operação fiável exige observar o ciclo de vida por camadas. Primeiro está a sessão: conectividade de transporte e estado de bind. Em seguida, a aceitação ou rejeição de submit_sm. Mais tarde, se for solicitado através de registered_delivery e a rota o suportar, pode chegar um recibo de entrega através de deliver_sm ou data_sm. Por fim, qualquer evidência independente de receção deve ser tratada como um sinal distinto da telemetria do SMSC.

O SMPP funciona sobre uma ligação subjacente, habitualmente TCP/IP, da qual o protocolo espera transferência fiável, controlo de fluxo e tratamento de erros de transporte. Uma desconexão, um timeout ou uma resposta que não chega não significam automaticamente que o SMSC não recebeu a solicitação. Nesse caso, existe risco de submissão duplicada se houver novo envio sem uma estratégia de correlação e idempotência na aplicação.

O estado consultável através de query_sm pode incluir ENROUTE, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN e REJECTED. Estes estados devem ser conservados tal como foram recebidos, com o momento da observação e o contexto da rota. Um estado posterior pode alterar a decisão inicial tomada após submit_sm_resp.

• Sessão: ligação ativa e bind válido para o tipo de operação.
• Aceitação: resultado de command_status em submit_sm_resp.
• Estado posterior: DLR ou query_sm, quando disponíveis.
• Evidência de receção: não deve ser inferida apenas a partir de uma aceitação de submit_sm nem de um formato textual de DLR.

Porque a mesma falha nem sempre exige a mesma ação

A ação não deve depender apenas do código. O mesmo erro pode ter consequências diferentes consoante o destino, o volume afetado, a criticidade da mensagem, o estado da sessão, a recorrência e a existência de alterações recentes de configuração. Um ESME_RTHROTTLED isolado exige reduzir a pressão; uma sequência sustentada em toda a ligação exige rever o controlo de ritmo e, possivelmente, pausar o fluxo.

Defina uma matriz de decisão que combine quatro fatores: classe do erro, alcance, criticidade e evidência disponível. Classifique o alcance como mensagem individual, destino específico, sessão, ligação ou conjunto de tráfego. Distinga mensagens que podem expirar funcionalmente, como um OTP, daquelas que admitem demora. Não amplifique um problema temporário com tentativas simultâneas e não transforme um erro de dados em tentativas repetidas.

A política deve ter limites explícitos. Cada tentativa precisa de um contador, um intervalo de espera, uma condição de saída e um mecanismo para evitar duplicados quando a incerteza está na resposta de rede. Quando não houver resposta conclusiva, registe o caso como incerto em vez de o classificar prematuramente como rejeitado ou entregue.

• Tentar novamente de forma controlada: apenas perante sinais temporários ou ambíguos que justifiquem investigação.
• Corrigir e reenviar: quando o código indicar parâmetros, endereçamento, credenciais ou estado de bind incorretos.
• Pausar e escalar: quando a falha afetar uma sessão, uma fila, uma capacidade ou um volume relevante.
• Encerrar: quando o problema for permanente, a mensagem perder utilidade ou os limites definidos pela política forem atingidos.

Taxonomia operacional de códigos e erros SMPP

A classificação prática deve preservar dois níveis: a semântica exata de command_status e uma categoria operacional interna. O primeiro nível evita a perda de informação. O segundo facilita automatização, alertas e decisões consistentes.

Uma taxonomia útil separa erros de construção de PDU, sessão e autenticação, capacidade ou limitação, endereçamento, conteúdo ou parâmetros, e erros de sistema ou fornecedor. Nem todos os códigos padrão resolvem a causa raiz por si só; por exemplo, ESME_RSYSERR é definido apenas como erro de sistema e não especifica duração, origem ou possibilidade de nova tentativa.

Não substitua o valor original por uma etiqueta simplificada. Registe o código hexadecimal, o nome SMPP quando existir, a PDU envolvida, o sequence_number, o command_status, o message_id quando disponível, o sistema remoto, os parâmetros não sensíveis de endereçamento e os eventos de sessão próximos da falha.

• Construção de PDU: corrigir serialização, comprimentos, campos e comando.
• Sessão e autenticação: restaurar bind e permissões antes de enviar tráfego.
• Capacidade: desacelerar, aplicar espera e monitorizar a recuperação.
• Endereçamento: normalizar os dados e validar a combinação de endereço, TON e NPI.
• Sistema ou fornecedor: preservar evidência, limitar tentativas e solicitar uma definição documentada se a semântica não for padrão.

Erros de sessão e bind: credenciais, permissões, modo de bind e saúde da ligação

submit_sm só pode ser emitido a partir de uma sessão no estado BOUND_TX ou BOUND_TRX. Emissão a partir de outro estado pode produzir ESME_RINVBNDSTS, definido como estado de bind incorreto para o comando. A ação correta não é reenviar imediatamente o mesmo submit: confirme o estado da sessão, conclua o bind adequado e verifique que o modo autorizado permite transmissão.

Os erros ESME_RBINDFAIL, ESME_RINVPASWD e ESME_RINVSYSID correspondem a falha de bind, palavra-passe inválida e identificador de sistema inválido. Devem ser tratados como erros que exigem correção. Tentar novamente com as mesmas credenciais amplifica as falhas e pode dificultar o diagnóstico.

Além do código, observe a saúde da ligação: encerramentos de socket, timeouts, ausência de resposta, reconexões frequentes e eventos de unbind. Quando uma solicitação fica sem resposta devido a uma ocorrência de transporte, não assuma que não foi processada. Antes de a repetir, aplique controlos de deduplicação e, se estiverem disponíveis e forem adequados, mecanismos de consulta ou reconciliação baseados nos identificadores conhecidos.

• Verifique que a sessão está em bind como transmissora ou transceptora antes de enviar submit_sm.
• Confirme system_id, palavra-passe, permissões e modo de bind com a configuração autorizada.
• Diferencie uma rejeição SMPP explícita de um timeout ou desconexão sem resposta.
• Não reprograme em paralelo mensagens incertas após uma falha de transporte sem uma estratégia contra duplicados.

Erros temporários: congestão, limites, capacidade e espera controlada

ESME_RTHROTTLED, código 0x00000058, indica que o ESME excedeu os limites de mensagens permitidos. Deve ser interpretado como um sinal para reduzir o ritmo de envio. A tentativa imediata, sobretudo a partir de vários processos em paralelo, mantém ou agrava o excesso que originou a rejeição.

ESME_RMSGQFUL, código 0x00000014, indica uma fila de mensagens cheia. Classifique-o como sinal de capacidade do SMSC ou da rota, separado dos erros de formato, credenciais ou endereçamento. Pode ser transitório, mas a norma não estabelece uma janela de recuperação nem garante que uma nova tentativa terá sucesso.

Aplique espera progressiva e um limite de tentativas coerente com a utilidade da mensagem. Reduza a concorrência ou o caudal antes de tentar novamente. Meça separadamente as rejeições por limitação, o tempo até à recuperação e o alcance por ligação ou destino. Se os erros persistirem, pause o tráfego afetado e abra uma investigação com registos completos.

• ESME_RTHROTTLED: reduzir o ritmo, controlar a concorrência e tentar novamente após espera.
• ESME_RMSGQFUL: tratar como limitação de capacidade e monitorizar se recupera.
• Evite tentativas simultâneas e sem limite.
• Interrompa as tentativas quando a mensagem deixar de ser útil, for atingido o máximo definido ou a ocorrência exigir escalamento.
• ESME_RSYSERR: investigar primeiro; a norma não permite concluir, por si só, que seja temporário ou passível de nova tentativa.

Erros permanentes ou que exigem correção: parâmetros inválidos, endereçamento, remetente e formato

Os erros de PDU exigem rever a construção da mensagem antes de uma nova submissão. ESME_RINVMSGLEN indica comprimento de mensagem inválido; ESME_RINVCMDLEN, comprimento de comando inválido; e ESME_RINVCMDID, identificador de comando inválido. Não são candidatos a uma tentativa idêntica: exigem correção da serialização ou da lógica de integração.

Em submit_sm, short_message admite até 254 octetos. A especificação adverte que o limite físico exato pode variar consoante a rede subjacente. Para mensagens superiores a 254 octetos, deve ser utilizado message_payload e short_message não deve ser usado simultaneamente. Este requisito não substitui a validação das regras aceites pelo SMSC para codificação, segmentação e outros parâmetros.

ESME_RINVSRCADR e ESME_RINVDSTADR indicam endereço de origem e destino inválidos, respetivamente. Existem também ESME_RINVDSTTON e ESME_RINVDSTNPI para TON e NPI do destino. Reveja o endereço como um conjunto: valor, TON, NPI e regra de aceitação da ligação. E.164 é uma referência internacional de numeração, mas uma aparência compatível com essa referência não garante que a combinação de endereço, TON, NPI e política do SMSC seja aceite.

Para remetentes, aplique a mesma prudência: um erro de endereço de origem exige rever o valor enviado e os parâmetros associados, além das regras da ligação. Não tente contornar restrições de remetente ou políticas de mensagens; corrija a configuração e confirme os requisitos aplicáveis à rota.

• ESME_RINVMSGLEN, ESME_RINVCMDLEN e ESME_RINVCMDID: corrigir a PDU; não repetir sem alterações.
• ESME_RINVSRCADR e ESME_RINVDSTADR: rever o valor de origem ou destino.
• ESME_RINVDSTTON e ESME_RINVDSTNPI: rever a combinação de endereço, TON e NPI.
• Para mensagens longas, não combine short_message com message_payload.
• Mantenha validação antes do envio para reduzir rejeições evitáveis.

Erros ambíguos ou específicos do fornecedor: preservar evidência e pedir uma definição documentada

Nem todo o código recebido tem uma semântica universal. O SMPP reserva intervalos para extensões e para fornecedores de SMSC. Se receber um código fora da tabela padrão, não o reatribua a uma causa genérica nem o traduza como falha de entrega sem documentação. Registe o valor exato e solicite ao sistema remoto uma definição técnica documentada.

Os recibos de entrega também exigem cautela. O SMPP permite que o SMSC devolva um delivery receipt através de deliver_sm ou data_sm quando foi solicitado com registered_delivery, mas o conteúdo textual informativo de um SMSC Delivery Receipt é específico do fornecedor. Não construa automatizações críticas com base apenas numa cadeia de texto assumida como universal.

Quando presente, network_error_code representa um código real de erro de rede específico da tecnologia. Preserve tanto o tipo de rede como o valor do código, além do estado SMPP e do texto original do DLR. Esta evidência permite investigar sem eliminar a distinção entre uma semântica SMPP padrão, um estado comunicado pelo SMSC e um código de rede subjacente.

Um bom processo de escalamento inclui cronologia, PDU e resposta relevantes, códigos originais, identificadores correlacionados, estado da sessão, percentagem e alcance das falhas, destinos afetados minimizados quando necessário e alterações recentes de configuração. Evite incluir credenciais ou dados desnecessários.

• Conserve command_status em hexadecimal e a respetiva interpretação padrão quando existir.
• Registe textos de DLR sem assumir que o respetivo formato é portável entre sistemas.
• Preserve network_error_code com o tipo de rede e o valor original.
• Solicite documentação para códigos de extensão ou específicos do fornecedor.
• Escale com evidência técnica suficiente e sem expor segredos de ligação.