# Códigos de erro command_status do SMPP

> O command_status é o campo de cabeçalho de 4 bytes que reporta o resultado de uma operação. Num pedido é 0 (ESME_ROK); numa resposta transporta um código de erro ESME_R*. 0x00000000 é sucesso; valores não nulos indicam falhas específicas como password inválida, limitação de taxa ou fila de mensagens cheia.

- URL canônico: https://www.broadnet.me/pt/reference/smpp-command-status-errors
- Idioma: pt
- Última atualização: 2026-07-18
- Editor: BroadNet (https://www.broadnet.me)

O campo command_status do SMPP e a gama de erros ESME_R*: o que significam os códigos comuns (ESME_RINVPASWD, ESME_RTHROTTLED, ESME_RMSGQFUL…) e como reagir a cada um.

## Como funciona o command_status

Cada PDU de resposta ecoa o sequence_number do pedido e define o command_status como o resultado. ESME_ROK (0) significa sucesso. Qualquer outro valor é um erro cujo código numérico mapeia para uma constante nomeada ESME_R* na especificação. Os códigos 0x00000100–0x000003FF estão reservados para extensões SMPP e 0x00000400–0x000004FF para erros específicos do fabricante do SMSC, por isso trate sempre códigos desconhecidos de forma graciosa.

## Os códigos que vai realmente ver

Um pequeno conjunto de códigos cobre a maioria do tratamento real. Agrupe-os por resposta: repetir-após-recuo (limitação de taxa, fila cheia, erro de sistema), corrigir-o-pedido (endereço inválido, TON/NPI, data_coding, comprimento da mensagem) e fatal-para-a-sessão (password ou ID de sistema inválidos, falha de bind).

*Códigos command_status encontrados frequentemente*

| Valor | Nome | Significado | Reação típica |
|---|---|---|---|
| 0x00000000 | ESME_ROK | Sem erros | Sucesso |
| 0x00000001 | ESME_RINVMSGLEN | Comprimento da mensagem inválido | Corrigir payload / segmento |
| 0x00000005 | ESME_RALYBND | Bind já estabelecido | Não refazer o bind; reutilizar a sessão |
| 0x0000000A | ESME_RINVSRCADR | Endereço de origem inválido | Corrigir remetente / TON / NPI |
| 0x0000000B | ESME_RINVDSTADR | Endereço de destino inválido | Corrigir MSISDN do destinatário |
| 0x0000000D | ESME_RBINDFAIL | Falha no bind | Backoff, verificar as credenciais |
| 0x0000000E | ESME_RINVPASWD | Palavra-passe inválida | Fatal — corrigir credenciais |
| 0x0000000F | ESME_RINVSYSID | ID do sistema inválido | Fatal — corrigir credenciais |
| 0x00000014 | ESME_RMSGQFUL | Fila de mensagens cheia | Backoff e nova tentativa |
| 0x00000043 | ESME_RINVESMCLASS | esm_class inválido | Corrigir bits de esm_class |
| 0x00000058 | ESME_RTHROTTLED | Throttling — taxa excedida | Reduzir a velocidade, backoff com jitter |
| 0x00000062 | ESME_RINVEXPIRY | validity_period inválido | Corrigir formato de validade |
| 0x000000FE | ESME_RDELIVERYFAILURE | Falha na entrega (data_sm) | Inspecionar/tentar novamente conforme a política |
| 0x000000FF | ESME_RUNKNOWNERR | Erro desconhecido | Registe, alerte, tente novamente com cautela |

## Gamas reservadas e de fabricante

Nem todos os códigos que recebe estão na especificação principal. A especificação reserva 0x00000100–0x000003FF para uso futuro do SMPP e 0x00000400–0x000004FF para códigos específicos do SMSC, pelo que o seu fornecedor pode devolver um valor que só a documentação dele explica. Mapeie os códigos específicos do fornecedor para uma taxonomia interna normalizada (número inválido, bloqueado, com limitação de taxa, falha temporária) para que a qualidade entre rotas se mantenha comparável.

*Gamas reservadas de command_status*

| Intervalo | Reservado para |
|---|---|
| 0x00000100 – 0x000003FF | Extensões do protocolo SMPP |
| 0x00000400 – 0x000004FF | Erros específicos do fornecedor SMSC |
| 0x00000500 – 0xFFFFFFFF | Reservado |

## Perguntas frequentes

### O que significa ESME_RTHROTTLED e como o devo tratar?

ESME_RTHROTTLED (0x00000058) significa que excedeu a taxa de mensagens permitida. Pare de aumentar a carga, suspenda os submits e recue com jitter antes de repetir. Insistir na mesma taxa arrisca que o fornecedor derrube o bind.

### O ESME_RINVPASWD é recuperável?

Não em tempo de execução. ESME_RINVPASWD (0x0000000E) indica credenciais erradas. Não faça hot-loop do bind; corrija a configuração de system_id/password e volte a ligar. Binds falhados repetidos podem despoletar bloqueio de IP.

### Qual é a diferença entre ESME_RMSGQFUL e ESME_RTHROTTLED?

ESME_RMSGQFUL (0x00000014) significa que a fila do SMSC está temporariamente cheia; ESME_RTHROTTLED (0x00000058) significa que excedeu o seu limite de taxa. Ambos exigem recuo, mas a limitação de taxa é sobre o seu TPS enquanto a fila cheia é sobre a capacidade do SMSC.

### Recebi um código de erro que não está na especificação — porquê?

O SMPP reserva 0x400–0x4FF para códigos específicos do fabricante do SMSC, pelo que o seu fornecedor pode devolver um valor documentado apenas por ele. Consulte a tabela de erros do fornecedor e mapeie-o para a sua taxonomia interna.

## Fontes

- [SMPP v3.4 specification — §5.1.3 command_status](https://smpp.org/SMPP_v3_4_Issue1_2.pdf)
- [SMPP v5.0 specification](https://smpp.org/SMPP_v5.pdf)

## Relacionados

- [Consulta de código de erro SMPP (ferramenta gratuita)](https://www.broadnet.me/pt/tools/smpp-error-codes)
- [Anatomia do PDU SMPP](https://www.broadnet.me/pt/reference/smpp-pdu-anatomy)
- [enquire_link SMPP e throttling](https://www.broadnet.me/pt/reference/smpp-enquire-link-throttling)
- [Melhores práticas de integração SMPP](https://www.broadnet.me/pt/reference/smpp-integration-best-practices)
- [Lista de verificação (guia) para integração SMPP](https://www.broadnet.me/pt/guides/smpp-integration-checklist)