Home / SMPP error codes
SMPP error codes: Every command_status, what it means and what to do
Every SMPP response (submit_sm_resp, bind_transceiver_resp…) carries a command_status. 0 means success; anything else is an error code defined by SMPP 3.4 or by the server vendor. This table lists the codes gateways actually return, what they mean and what to do about each.
How to read a command_status
The value is a 32-bit integer, usually logged in hex (0x00000058) or decimal (88). Codes 0x00000000–0x000000FF are defined by the SMPP 3.4 specification; 0x00000400–0x000004FF are reserved for vendor-specific errors, so check your provider's documentation for those.
A non-zero command_status on submit_sm_resp means the message was not accepted: it was not sent and, on most platforms, not charged. A delivery problem after acceptance is reported later in a delivery receipt, not as a command_status.
Errors you should retry
Only a few codes are temporary: ESME_RTHROTTLED (0x58), ESME_RMSGQFUL (0x14), ESME_RSYSERR (0x08) and ESME_RX_T_APPN (0x64). Retry them with a growing delay. Retrying any other code without changing the request returns the same error.
All codes
| Hex | Decimal | Name | Meaning | What to do |
|---|---|---|---|---|
| 0x00000000 | 0 | ESME_ROK | No error | Nothing: the message was accepted. |
| 0x00000001 | 1 | ESME_RINVMSGLEN | Message length is invalid | Check the encoding and the length of short_message (max 254 octets; longer texts go in message_payload or as concatenated parts). |
| 0x00000002 | 2 | ESME_RINVCMDLEN | Command length is invalid | The PDU is malformed: check the client library or the PDU encoder. |
| 0x00000003 | 3 | ESME_RINVCMDID | Invalid command ID | The server does not support this command (e.g. submit_multi or query_sm): use submit_sm. |
| 0x00000004 | 4 | ESME_RINVBNDSTS | Incorrect bind status for this command | Bind as transmitter or transceiver to submit, as receiver or transceiver to get receipts. |
| 0x00000005 | 5 | ESME_RALYBND | Already bound | The session is already bound: do not send a second bind on the same connection. |
| 0x00000006 | 6 | ESME_RINVPRTFLG | Invalid priority flag | Use priority_flag 0 to 3 (most gateways ignore it: send 0). |
| 0x00000007 | 7 | ESME_RINVREGDLVFLG | Invalid registered delivery flag | Use registered_delivery 0 (no receipt) or 1 (receipt on success and failure). |
| 0x00000008 | 8 | ESME_RSYSERR | System error | A temporary problem on the server side: retry later with back-off; contact support if it persists. |
| 0x0000000A | 10 | ESME_RINVSRCADR | Invalid source address | Check the sender: alphanumeric max 11 characters (TON 5, NPI 0), or a number in international format (TON 1, NPI 1). |
| 0x0000000B | 11 | ESME_RINVDSTADR | Invalid destination address | Send the number in international format without "+" or leading zeros (TON 1, NPI 1). |
| 0x0000000C | 12 | ESME_RINVMSGID | Message ID is invalid | The message_id does not exist or is not yours (query_sm / cancel_sm). |
| 0x0000000D | 13 | ESME_RBINDFAIL | Bind failed | Check system_id, password, the allowed IP addresses and how many binds the account may open. |
| 0x0000000E | 14 | ESME_RINVPASWD | Invalid password | Check the password of the SMPP account (case-sensitive, max 8 characters on many servers). |
| 0x0000000F | 15 | ESME_RINVSYSID | Invalid system ID | Check the system_id of the SMPP account. |
| 0x00000011 | 17 | ESME_RCANCELFAIL | Cancel SM failed | The message could not be cancelled (already sent or not found). |
| 0x00000013 | 19 | ESME_RREPLACEFAIL | Replace SM failed | The message could not be replaced (already sent or not found). |
| 0x00000014 | 20 | ESME_RMSGQFUL | Message queue full | Slow down and retry: the server queue is full. |
| 0x00000015 | 21 | ESME_RINVSERTYP | Invalid service type | Leave service_type empty unless your provider gave you a value. |
| 0x00000033 | 51 | ESME_RINVNUMDESTS | Invalid number of destinations | submit_multi: check number_of_dests. |
| 0x00000034 | 52 | ESME_RINVDLNAME | Invalid distribution list name | submit_multi: check the distribution list name. |
| 0x00000040 | 64 | ESME_RINVDESTFLAG | Invalid destination flag | submit_multi: dest_flag must be 1 (address) or 2 (list). |
| 0x00000042 | 66 | ESME_RINVSUBREP | Invalid submit with replace | Set replace_if_present_flag to 0. |
| 0x00000043 | 67 | ESME_RINVESMCLASS | Invalid esm_class field | Use esm_class 0, or 0x40 when the text carries a UDH (concatenated parts). |
| 0x00000044 | 68 | ESME_RCNTSUBDL | Cannot submit to distribution list | Submit to single numbers. |
| 0x00000045 | 69 | ESME_RSUBMITFAIL | submit_sm or submit_multi failed | The server refused the message (route, balance or content): check the account and retry later. |
| 0x00000048 | 72 | ESME_RINVSRCTON | Invalid source address TON | Alphanumeric sender: TON 5; international number: TON 1. |
| 0x00000049 | 73 | ESME_RINVSRCNPI | Invalid source address NPI | Alphanumeric sender: NPI 0; international number: NPI 1. |
| 0x00000050 | 80 | ESME_RINVDSTTON | Invalid destination address TON | Use TON 1 (international). |
| 0x00000051 | 81 | ESME_RINVDSTNPI | Invalid destination address NPI | Use NPI 1 (ISDN / E.164). |
| 0x00000053 | 83 | ESME_RINVSYSTYP | Invalid system_type field | Leave system_type empty unless your provider gave you a value. |
| 0x00000054 | 84 | ESME_RINVREPFLAG | Invalid replace_if_present flag | Set replace_if_present_flag to 0. |
| 0x00000055 | 85 | ESME_RINVNUMMSGS | Invalid number of messages | Check the request parameters. |
| 0x00000058 | 88 | ESME_RTHROTTLED | Throttling error (too many messages per second) | Send slower than the speed of your account, or spread the traffic over more binds if allowed; retry the refused messages. |
| 0x00000061 | 97 | ESME_RINVSCHED | Invalid scheduled delivery time | Use the SMPP absolute (YYMMDDhhmmsstnnp) or relative (…R) time format, or leave it empty. |
| 0x00000062 | 98 | ESME_RINVEXPIRY | Invalid validity period | Use the SMPP time format, or leave it empty for the default validity. |
| 0x00000063 | 99 | ESME_RINVDFTMSGID | Predefined message invalid or not found | Set sm_default_msg_id to 0. |
| 0x00000064 | 100 | ESME_RX_T_APPN | Receiver temporary application error | Temporary: retry later. |
| 0x00000065 | 101 | ESME_RX_P_APPN | Receiver permanent application error | Permanent: do not retry this message as it is. |
| 0x00000066 | 102 | ESME_RX_R_APPN | Receiver reject message error | The message was refused: do not retry it as it is. |
| 0x00000067 | 103 | ESME_RQUERYFAIL | query_sm request failed | The message could not be queried (unknown or too old). |
| 0x000000C0 | 192 | ESME_RINVOPTPARSTREAM | Error in the optional part of the PDU body | A TLV is malformed: check the client library. |
| 0x000000C1 | 193 | ESME_ROPTPARNOTALLWD | Optional parameter not allowed | Remove the TLV the server does not accept. |
| 0x000000C2 | 194 | ESME_RINVPARLEN | Invalid parameter length | A TLV has a wrong length: check the client library. |
| 0x000000C3 | 195 | ESME_RMISSINGOPTPARAM | Expected optional parameter missing | Add the TLV the server requires (see the provider documentation). |
| 0x000000C4 | 196 | ESME_RINVOPTPARAMVAL | Invalid optional parameter value | Check the value of the TLVs you send. |
| 0x000000FE | 254 | ESME_RDELIVERYFAILURE | Delivery failure (data_sm_resp) | The message could not be delivered: see the receipt or retry later. |
| 0x000000FF | 255 | ESME_RUNKNOWNERR | Unknown error | An unspecified error on the server: contact support with the message ID and the time. |
Frequently asked questions
What does ESME_RTHROTTLED (0x58) mean?
You are sending faster than the speed allowed for your account. Slow down to that speed (or spread traffic across the binds you are allowed) and resend the refused messages.
Is a message with an error code charged?
A message refused with a non-zero command_status was not accepted, so on most platforms it is not charged. Check your provider's terms.
Why do I get ESME_RINVDSTADR (0x0B)?
The destination number is not in the format the server expects. Send it in international format, digits only, with TON 1 and NPI 1.
What is the difference between a command_status and a delivery receipt error?
command_status answers your request at once (accepted or not). A delivery receipt arrives later and says whether the accepted message reached the phone, with its own stat and err fields.
Read more
Talk to a technical team
We're a technical team. You'll talk to someone who understands SMPP, wholesale routing, and carrier interconnects. Technical proposal in under 24 hours.
Technical email: 