Códigos de erro SMPP.
Cada valor command_status definido na especificação SMPP v3.4 — código hexadecimal, nome simbólico, significado em linguagem simples e causa provável e correção. Pesquise por código ou nome para depurar rapidamente uma falha de bind ou submit_sm.
| Hexadecimal | Nome simbólico | Significado e causa provável / correção |
|---|---|---|
| 0x00000000 | ESME_ROK | Sem erro. A PDU foi aceite. Em submit_sm, isto significa apenas que o SMSC aceitou a mensagem para processamento, não que foi entregue — acompanhe a entrega através do relatório de entrega (DLR) em deliver_sm. |
| 0x00000001 | ESME_RINVMSGLEN | Comprimento da mensagem inválido. short_message ou message_payload é demasiado longo ou está vazio para a codificação usada. Segmente o conteúdo longo ou use o TLV message_payload; verifique se data_coding corresponde ao comprimento em bytes. |
| 0x00000002 | ESME_RINVCMDLEN | Comprimento de comando inválido. O command_length no cabeçalho da PDU não corresponde aos bytes efetivamente enviados. Quase sempre um erro do codificador de PDU do cliente ou um erro de fronteira de framing/buffer. |
| 0x00000003 | ESME_RINVCMDID | ID de comando inválido. O command_id é desconhecido ou não suportado pelo SMSC. Verifique se está a enviar uma operação válida e a versão correta do SMPP. |
| 0x00000004 | ESME_RINVBNDSTS | Estado BIND incorreto para o comando indicado. Operação não permitida no modo de bind atual — por exemplo, submit_sm num bind receiver, ou um pedido antes de o bind estar concluído. Faça primeiro bind como transmitter ou transceiver. |
| 0x00000005 | ESME_RALYBND | O ESME já está em estado de bind. Foi emitido um segundo bind numa sessão já ligada. Reutilize a sessão existente ou faça unbind antes de voltar a ligar. |
| 0x00000006 | ESME_RINVPRTFLG | Sinalizador de prioridade inválido. priority_flag está fora do intervalo 0–3 aceite pelo SMSC. Use um valor suportado (normalmente 0). |
| 0x00000007 | ESME_RINVREGDLVFLG | Sinalizador de entrega registada inválido. registered_delivery contém um valor não suportado. Use uma máscara de bits aceite pelo SMSC (por ex., 0x01 para pedir um DLR final). |
| 0x00000008 | ESME_RSYSERR | Erro de sistema. Falha genérica do lado do SMSC que impede o processamento. Transitório — tente novamente com backoff; se persistir, contacte o fornecedor. |
| 0x0000000A | ESME_RINVSRCADR | Endereço de origem inválido. source_addr (o ID do remetente) está malformado ou não é permitido — comprimento errado, caracteres inválidos, ou um remetente alfanumérico não registado. Registe ou autorize o remetente. |
| 0x0000000B | ESME_RINVDSTADR | Endereço de destino inválido. destination_addr está malformado ou não é encaminhável — formato de MSISDN incorreto, indicativo de país em falta, ou intervalo bloqueado. Normalize para o formato E.164. |
| 0x0000000C | ESME_RINVMSGID | ID de mensagem inválido. O message_id num query_sm, cancel_sm ou replace_sm não corresponde a nenhuma mensagem conhecida. Use o ID exato devolvido em submit_sm_resp. |
| 0x0000000D | ESME_RBINDFAIL | Bind falhou. O pedido de bind foi rejeitado por um motivo diferente das credenciais — por ex., IP não autorizado, TLS obrigatório, ou tipo de bind não permitido para a conta. |
| 0x0000000E | ESME_RINVPASWD | Palavra-passe inválida. A palavra-passe na PDU de bind está incorreta ou expirou. Verifique as credenciais; o campo está limitado a 8 octetos no SMPP 3.4. |
| 0x0000000F | ESME_RINVSYSID | ID de sistema inválido. O system_id (nome de utilizador) é desconhecido do SMSC. Verifique o identificador da conta e se está ativo. |
| 0x00000011 | ESME_RCANCELFAIL | Cancel SM falhou. cancel_sm não conseguiu remover a mensagem — pode já ter sido entregue ou ter expirado. Nada a repetir. |
| 0x00000013 | ESME_RREPLACEFAIL | Replace SM falhou. replace_sm não conseguiu atualizar a mensagem, normalmente porque já saiu da fila. Envie uma nova mensagem em alternativa. |
| 0x00000014 | ESME_RMSGQFUL | Fila de mensagens cheia. A fila de armazenamento e reenvio do SMSC está na capacidade máxima. Reduza a taxa de envio e tente novamente com backoff. |
| 0x00000015 | ESME_RINVSERTYP | Tipo de serviço inválido. O valor de service_type não é reconhecido ou não é permitido. Deixe-o nulo ou use um valor acordado com o fornecedor. |
| 0x00000033 | ESME_RINVNUMDESTS | Número de destinos inválido. number_of_dests numa PDU submit_multi está fora do intervalo. Mantenha-se dentro do limite de destinos por PDU do SMSC. |
| 0x00000034 | ESME_RINVDLNAME | Nome de lista de distribuição inválido. A lista de distribuição referenciada em submit_multi não existe no SMSC. Crie a lista ou envie para endereços explícitos. |
| 0x00000040 | ESME_RINVDESTFLAG | Sinalizador de destino inválido. Em submit_multi, o dest_flag de uma entrada não é nem um endereço SME (1) nem uma lista de distribuição (2). Corrija o sinalizador por destino. |
| 0x00000042 | ESME_RINVSUBREP | Pedido de 'envio com substituição' inválido. replace_if_present_flag foi definido numa operação que não o suporta, ou combinado com listas de distribuição. Remova o sinalizador. |
| 0x00000043 | ESME_RINVESMCLASS | Dados do campo esm_class inválidos. esm_class contém uma combinação não suportada — por ex., um bit UDHI ou de relatório de entrega rejeitado pelo SMSC. Reveja os bits de modo/tipo da mensagem. |
| 0x00000044 | ESME_RCNTSUBDL | Não é possível enviar para a lista de distribuição. A conta não tem permissão para enviar para a lista de distribuição indicada. Use o endereçamento direto ou peça autorização. |
| 0x00000045 | ESME_RSUBMITFAIL | submit_sm ou submit_multi falhou. Falha genérica de envio no lado do SMSC. Muitas vezes transitória (encaminhamento/capacidade) — tente novamente com backoff; inspecione os TLV para um motivo mais específico. |
| 0x00000048 | ESME_RINVSRCTON | TON do endereço de origem inválido. source_addr_ton não é válido para o formato do remetente — por ex., é necessário TON 5 (alfanumérico) para um remetente de texto, mas foi enviado um TON numérico. |
| 0x00000049 | ESME_RINVSRCNPI | NPI do endereço de origem inválido. source_addr_npi é inválido ou incoerente com o TON. Use NPI 0 com remetentes alfanuméricos e NPI 1 (E.164) para MSISDN. |
| 0x00000050 | ESME_RINVDSTTON | TON do endereço de destino inválido. dest_addr_ton é inválido para o destino. Use TON 1 (internacional) com um MSISDN em formato E.164. |
| 0x00000051 | ESME_RINVDSTNPI | NPI do endereço de destino inválido. dest_addr_npi é inválido ou incoerente com o TON. NPI 1 (ISDN/E.164) é o valor habitual para números móveis. |
| 0x00000053 | ESME_RINVSYSTYP | Campo system_type inválido. O system_type na PDU de bind não é aceite. Deixe-o nulo ou use o valor exato atribuído pelo fornecedor. |
| 0x00000054 | ESME_RINVREPFLAG | Sinalizador replace_if_present inválido. replace_if_present_flag está definido com um valor diferente de 0 ou 1. Envie um sinalizador booleano válido. |
| 0x00000055 | ESME_RINVNUMMSGS | Número de mensagens inválido. O campo sm_count / número de mensagens está fora do intervalo. Corrija o valor na PDU. |
| 0x00000058 | ESME_RTHROTTLED | Erro de limitação — limite de mensagens excedido. Está a enviar mais rápido do que a taxa permitida para a conta (mensagens por segundo). Reduza o ritmo de envio e tente novamente com backoff. Condição transitória e repetível. |
| 0x00000061 | ESME_RINVSCHED | Hora de entrega agendada inválida. schedule_delivery_time está malformado ou no passado. Use o formato de hora SMPP absoluto/relativo (YYMMDDhhmmsstnnp) ou deixe-o nulo. |
| 0x00000062 | ESME_RINVEXPIRY | Período de validade da mensagem inválido. validity_period está malformado ou fora da janela permitida. Use o formato de hora SMPP ou deixe-o nulo para o valor predefinido do SMSC. |
| 0x00000063 | ESME_RINVDFTMSGID | Mensagem predefinida inválida ou não encontrada. sm_default_msg_id refere-se a uma mensagem predefinida que o SMSC não possui. Envie o texto completo ou um ID predefinido válido. |
| 0x00000064 | ESME_RX_T_APPN | Código de erro de aplicação temporário do recetor ESME. Devolvido pelo seu ESME (ou por um sistema a montante) para sinalizar uma falha de aplicação temporária ao processar deliver_sm/data_sm. O SMSC pode tentar novamente a entrega mais tarde. |
| 0x00000065 | ESME_RX_P_APPN | Código de erro de aplicação permanente do recetor ESME. A aplicação recetora rejeita a mensagem de forma permanente. O SMSC não tentará novamente — corrija o processador a jusante ou o motivo da rejeição. |
| 0x00000066 | ESME_RX_R_APPN | Código de erro de rejeição de mensagem do recetor ESME. A aplicação recetora pede ao SMSC que rejeite a mensagem. Usado para recusar conteúdo recebido específico. |
| 0x00000067 | ESME_RQUERYFAIL | Pedido query_sm falhou. Não foi possível concluir a consulta de estado — o message_id pode ser desconhecido ou ter expirado do armazenamento do SMSC. Verifique o ID. |
| 0x000000C0 | ESME_RINVOPTPARSTREAM | Erro na parte opcional do corpo da PDU. O fluxo TLV (parâmetro opcional) está malformado — comprimento incorreto ou truncado. Corrija o codificador de TLV do seu cliente. |
| 0x000000C1 | ESME_ROPTPARNOTALLWD | Parâmetro opcional não permitido. Foi enviado um TLV que esta operação ou o SMSC não permite. Remova o parâmetro opcional não suportado. |
| 0x000000C2 | ESME_RINVPARLEN | Comprimento de parâmetro inválido. O comprimento declarado de um TLV não corresponde ao seu valor. Corrija o campo de comprimento do parâmetro opcional. |
| 0x000000C3 | ESME_RMISSINGOPTPARAM | Falta o parâmetro opcional esperado. Não foi fornecido um TLV necessário para esta operação (por ex., message_payload quando short_message está vazio). Adicione o parâmetro opcional obrigatório. |
| 0x000000C4 | ESME_RINVOPTPARAMVAL | Valor de parâmetro opcional inválido. Um TLV tem um valor fora do conjunto permitido. Consulte a especificação SMPP para os valores permitidos desse parâmetro. |
| 0x000000FE | ESME_RDELIVERYFAILURE | Falha de entrega (data_sm_resp). Usado com data_sm para indicar que a mensagem não pôde ser entregue ao telemóvel. Trate como um DLR falhado e inspecione a rede/rota. |
| 0x000000FF | ESME_RUNKNOWNERR | Erro desconhecido. Valor genérico quando o SMSC não tem um código específico. Tente novamente uma vez com backoff; se persistir, reporte ao fornecedor com uma amostra da PDU. |
Os valores não listados estão reservados. Segundo a especificação SMPP v3.4: 0x00000100–0x000003FF está reservado para extensões do protocolo SMPP, 0x00000400–0x000004FF para erros específicos do fornecedor do SMSC, e 0x00000500–0xFFFFFFFF está reservado. Lacunas individuais abaixo de 0xFF (por ex., 0x09, 0x10) estão reservadas pela norma.
A resposta curta
O que é um código de erro SMPP?
Um código de erro SMPP é o valor no campo command_status de cada PDU de resposta SMPP. Diz ao cliente (ESME) se o SMSC aceitou a operação — 0x00000000 (ESME_ROK) significa sucesso, e qualquer valor diferente de zero identifica porque um bind, submit_sm, query_sm ou outro pedido falhou. Os códigos são definidos pela especificação SMPP v3.4 e são consistentes em todos os SMSC compatíveis.
Um submit_sm_resp bem-sucedido com ESME_ROK confirma apenas que o SMSC aceitou a mensagem para processamento — a entrega final ao telemóvel é reportada separadamente no relatório de entrega (deliver_sm). Trate os erros no momento do envio e no momento da entrega como duas camadas diferentes.
Perguntas frequentes
O que é command_status em SMPP?
command_status é um campo de 4 bytes no cabeçalho de cada PDU de resposta SMPP. Numa PDU de pedido está a zero; numa resposta transporta o resultado — 0x00000000 (ESME_ROK) para sucesso ou um código de erro diferente de zero que identifica a falha. É o sinal principal que o seu cliente usa para decidir se tenta novamente, corrige a PDU, ou falha.
O que significa ESME_RTHROTTLED (0x00000058)?
Significa que está a enviar mensagens mais rápido do que a taxa permitida para a sua conta (mensagens por segundo). Reduza o seu ciclo de envio, aplique um backoff exponencial e mantenha-se dentro do débito acordado com o seu fornecedor. É uma condição transitória e repetível.
Qual é a diferença entre ESME_RINVSRCADR e ESME_RINVDSTADR?
ESME_RINVSRCADR (0x0000000A) significa que o endereço de origem — o seu ID de remetente — está malformado ou não é permitido, muitas vezes um remetente alfanumérico não registado. ESME_RINVDSTADR (0x0000000B) significa que o MSISDN de destino está malformado ou não é encaminhável. Normalize os endereços para E.164 e registe os IDs de remetente onde necessário.
ESME_ROK significa que a mensagem foi entregue?
Não. ESME_ROK em submit_sm_resp confirma apenas que o SMSC aceitou a mensagem para processamento. A entrega final ao telemóvel é reportada mais tarde no relatório de entrega (deliver_sm), que transporta o seu próprio estado como DELIVRD, UNDELIV ou EXPIRED. Concilie sempre a aceitação do envio com o DLR.
Que erros SMPP são seguros de repetir?
Os códigos transitórios do lado do sistema são repetíveis com backoff: ESME_RSYSERR (0x08), ESME_RMSGQFUL (0x14), ESME_RTHROTTLED (0x58), ESME_RSUBMITFAIL (0x45) e ESME_RUNKNOWNERR (0xFF). Erros de validação como endereços inválidos, TON/NPI, comprimento da mensagem ou credenciais incorretas são permanentes — corrija o pedido ou a configuração em vez de repetir.
Estes códigos são iguais em todos os SMSC?
Os códigos 0x00000000–0x000000FF são definidos pela especificação SMPP v3.4 e são consistentes em todos os SMSC compatíveis. Os intervalos 0x00000400–0x000004FF estão reservados para erros específicos do fornecedor, pelo que um determinado SMSC pode devolver aí códigos adicionais com significados próprios — verifique sempre a documentação do seu fornecedor para esses casos.
A especificação por trás desta ferramenta, na biblioteca de referência.
SMSC de qualidade de operadora sobre SMPP + SS7.
REST + SMPP 3.4, autenticação por token Bearer, webhooks de entrega.
Início rápido, TypeScript SDK, referências e ferramentas.
A estabelecer uma sessão SMPP?
A BroadNet oferece ligações SMPP 3.4 diretas com débito previsível e tratamento claro de command_status. Fale com a nossa equipa sobre uma ligação.