SMPP error codes.
Every command_status value defined in the SMPP v3.4 specification — hex code, symbolic name, plain-English meaning and the likely cause and fix. Search by code or name to debug a bind or submit_sm failure fast.
| Hex | Symbolic name | Meaning & likely cause / fix |
|---|---|---|
| 0x00000000 | ESME_ROK | No error. The PDU was accepted. For submit_sm this only means the SMSC took the message, not that it was delivered — track delivery via the DLR (deliver_sm). |
| 0x00000001 | ESME_RINVMSGLEN | Message length is invalid. short_message / message_payload is too long or zero for the encoding. Segment long content or use the message_payload TLV; check data_coding vs byte length. |
| 0x00000002 | ESME_RINVCMDLEN | Command length is invalid. The PDU command_length header does not match the actual bytes sent. Almost always a client-side PDU encoder bug or a framing/buffer boundary error. |
| 0x00000003 | ESME_RINVCMDID | Invalid command ID. The command_id is unknown or not supported by the SMSC. Check you are sending a valid operation and the correct SMPP version. |
| 0x00000004 | ESME_RINVBNDSTS | Incorrect BIND status for given command. Operation not allowed in the current bind mode — e.g. submit_sm on a receiver bind, or a request before bind completes. Bind as transmitter/transceiver first. |
| 0x00000005 | ESME_RALYBND | ESME already in bound state. A second bind was issued on a session that is already bound. Reuse the existing session or unbind before re-binding. |
| 0x00000006 | ESME_RINVPRTFLG | Invalid priority flag. priority_flag is outside the 0–3 range the SMSC accepts. Set a supported value (usually 0). |
| 0x00000007 | ESME_RINVREGDLVFLG | Invalid registered delivery flag. registered_delivery holds an unsupported value. Use a bitmask the SMSC supports (e.g. 0x01 to request a final DLR). |
| 0x00000008 | ESME_RSYSERR | System error. Generic SMSC-side failure that prevents processing. Transient — retry with backoff; if persistent, contact the provider. |
| 0x0000000A | ESME_RINVSRCADR | Invalid source address. The source_addr (sender ID) is malformed or not permitted — wrong length, illegal characters, or an unregistered alphanumeric sender ID. Register/whitelist the sender. |
| 0x0000000B | ESME_RINVDSTADR | Invalid destination address. destination_addr is malformed or unroutable — bad MSISDN format, missing country code, or a barred range. Normalise to E.164. |
| 0x0000000C | ESME_RINVMSGID | Message ID is invalid. The message_id in a query_sm, cancel_sm or replace_sm does not match a known message. Use the exact ID returned in submit_sm_resp. |
| 0x0000000D | ESME_RBINDFAIL | Bind failed. The bind request was rejected for a reason other than credentials — e.g. IP not allow-listed, TLS required, or bind type not permitted for the account. |
| 0x0000000E | ESME_RINVPASWD | Invalid password. The password in the bind PDU is wrong or expired. Verify credentials; note the field is limited to 8 octets in SMPP 3.4. |
| 0x0000000F | ESME_RINVSYSID | Invalid system ID. The system_id (username) is unknown to the SMSC. Check the account identifier and that it is enabled. |
| 0x00000011 | ESME_RCANCELFAIL | Cancel SM failed. cancel_sm could not remove the message — it may already be delivered or expired. Nothing to retry. |
| 0x00000013 | ESME_RREPLACEFAIL | Replace SM failed. replace_sm could not update the message, usually because it has already left the queue. Submit a new message instead. |
| 0x00000014 | ESME_RMSGQFUL | Message queue full. The SMSC store-and-forward queue is at capacity. Slow your submit rate and retry with backoff. |
| 0x00000015 | ESME_RINVSERTYP | Invalid service type. The service_type value is not recognised or not permitted. Leave it null or use a value agreed with the provider. |
| 0x00000033 | ESME_RINVNUMDESTS | Invalid number of destinations. number_of_dests in a submit_multi PDU is out of range. Keep it within the SMSC's per-PDU destination limit. |
| 0x00000034 | ESME_RINVDLNAME | Invalid distribution list name. The distribution list referenced in submit_multi does not exist on the SMSC. Create the list or send to explicit addresses. |
| 0x00000040 | ESME_RINVDESTFLAG | Destination flag is invalid. In submit_multi, the dest_flag for an entry is neither an SME address (1) nor a distribution list (2). Fix the per-destination flag. |
| 0x00000042 | ESME_RINVSUBREP | Invalid 'submit with replace' request. replace_if_present_flag was set on an operation that does not support it, or combined with distribution lists. Clear the flag. |
| 0x00000043 | ESME_RINVESMCLASS | Invalid esm_class field data. esm_class holds an unsupported combination — e.g. a UDHI or delivery-receipt bit the SMSC rejects. Recheck the message mode/type bits. |
| 0x00000044 | ESME_RCNTSUBDL | Cannot submit to distribution list. The account is not permitted to submit to the given distribution list. Use direct addressing or request permission. |
| 0x00000045 | ESME_RSUBMITFAIL | submit_sm or submit_multi failed. Generic submit failure at the SMSC. Often transient (routing/capacity) — retry with backoff; inspect any TLVs for a more specific reason. |
| 0x00000048 | ESME_RINVSRCTON | Invalid source address TON. source_addr_ton is not valid for the sender format — e.g. TON 5 (alphanumeric) required for a text sender ID but a numeric TON was sent. |
| 0x00000049 | ESME_RINVSRCNPI | Invalid source address NPI. source_addr_npi is invalid or inconsistent with the TON. Use NPI 0 with alphanumeric senders and NPI 1 (E.164) for MSISDNs. |
| 0x00000050 | ESME_RINVDSTTON | Invalid destination address TON. dest_addr_ton is invalid for the destination. Use TON 1 (international) with an E.164 MSISDN. |
| 0x00000051 | ESME_RINVDSTNPI | Invalid destination address NPI. dest_addr_npi is invalid or inconsistent with the TON. NPI 1 (ISDN/E.164) is the usual value for mobile numbers. |
| 0x00000053 | ESME_RINVSYSTYP | Invalid system_type field. The system_type in the bind PDU is not accepted. Leave it null or use the exact value the provider assigned. |
| 0x00000054 | ESME_RINVREPFLAG | Invalid replace_if_present flag. replace_if_present_flag is set to a value other than 0 or 1. Send a valid boolean flag. |
| 0x00000055 | ESME_RINVNUMMSGS | Invalid number of messages. The sm_count / number-of-messages field is out of range. Correct the value in the PDU. |
| 0x00000058 | ESME_RTHROTTLED | Throttling error — message limit exceeded. You are submitting faster than the account's permitted rate (messages per second). Throttle your submit loop and retry with backoff. |
| 0x00000061 | ESME_RINVSCHED | Invalid scheduled delivery time. schedule_delivery_time is malformed or in the past. Use the SMPP absolute/relative time format (YYMMDDhhmmsstnnp) or leave it null. |
| 0x00000062 | ESME_RINVEXPIRY | Invalid message validity period (expiry). validity_period is malformed or outside the allowed window. Use the SMPP time format or leave it null for the SMSC default. |
| 0x00000063 | ESME_RINVDFTMSGID | Predefined message invalid or not found. sm_default_msg_id references a canned message the SMSC does not have. Send the full text or a valid predefined ID. |
| 0x00000064 | ESME_RX_T_APPN | ESME receiver temporary app error code. Returned by your ESME (or an upstream) to signal a temporary application failure handling deliver_sm/data_sm. The SMSC may retry delivery later. |
| 0x00000065 | ESME_RX_P_APPN | ESME receiver permanent app error code. The receiving application permanently rejects the message. The SMSC will not retry — fix the downstream handler or reject reason. |
| 0x00000066 | ESME_RX_R_APPN | ESME receiver reject message error code. The receiving application asks the SMSC to reject the message. Used to decline specific inbound content. |
| 0x00000067 | ESME_RQUERYFAIL | query_sm request failed. The status query could not be completed — the message_id may be unknown or expired from the SMSC store. Verify the ID. |
| 0x000000C0 | ESME_RINVOPTPARSTREAM | Error in the optional part of the PDU body. The TLV (optional parameter) stream is malformed — bad length or truncated. Fix the TLV encoder in your client. |
| 0x000000C1 | ESME_ROPTPARNOTALLWD | Optional parameter not allowed. A TLV was sent that this operation or SMSC does not permit. Remove the unsupported optional parameter. |
| 0x000000C2 | ESME_RINVPARLEN | Invalid parameter length. A TLV's declared length does not match its value. Correct the length field in the optional parameter. |
| 0x000000C3 | ESME_RMISSINGOPTPARAM | Expected optional parameter missing. A TLV required for this operation was not supplied (e.g. message_payload when short_message is empty). Add the mandatory optional parameter. |
| 0x000000C4 | ESME_RINVOPTPARAMVAL | Invalid optional parameter value. A TLV carries a value outside its allowed set. Check the SMPP spec for the parameter's permitted values. |
| 0x000000FE | ESME_RDELIVERYFAILURE | Delivery failure (data_sm_resp). Used with data_sm to indicate the message could not be delivered to the handset. Treat like a failed DLR and inspect network/route. |
| 0x000000FF | ESME_RUNKNOWNERR | Unknown error. Catch-all when the SMSC has no specific code. Retry once with backoff; if it persists, raise it with the provider with a PDU sample. |
Values not listed are reserved. Per the SMPP v3.4 spec: 0x00000100–0x000003FF is reserved for SMPP protocol extensions, 0x00000400–0x000004FF for SMSC-vendor-specific errors, and 0x00000500–0xFFFFFFFF is reserved. Individual gaps below 0xFF (e.g. 0x09, 0x10) are reserved by the standard.
The short answer
What is an SMPP error code?
An SMPP error code is the value in the command_status field of every SMPP response PDU. It tells the client (ESME) whether the SMSC accepted the operation — 0x00000000 (ESME_ROK) means success, and any non-zero value identifies why a bind, submit_sm, query_sm or other request failed. The codes are defined by the SMPP v3.4 specification and are consistent across compliant SMSCs.
A successful submit_sm_resp with ESME_ROK confirms only that the SMSC accepted the message for processing — final delivery to the handset is reported separately in the delivery receipt (deliver_sm). Treat submit-time errors and delivery-time errors as two different layers.
Frequently asked questions
What is command_status in SMPP?
command_status is a 4-byte field in the header of every SMPP response PDU. In a request PDU it is set to zero; in a response it carries the result — 0x00000000 (ESME_ROK) for success or a non-zero error code identifying the failure. It is the primary signal your client uses to decide whether to retry, fix the PDU, or fail.
What does ESME_RTHROTTLED (0x00000058) mean?
It means you are submitting messages faster than your account's permitted rate (messages per second). Slow your submit loop, apply exponential backoff, and stay within the throughput agreed with your provider. It is a transient, retryable condition.
What is the difference between ESME_RINVSRCADR and ESME_RINVDSTADR?
ESME_RINVSRCADR (0x0000000A) means the source address — your sender ID — is malformed or not permitted, often an unregistered alphanumeric sender. ESME_RINVDSTADR (0x0000000B) means the destination MSISDN is malformed or unroutable. Normalise addresses to E.164 and register sender IDs where required.
Does ESME_ROK mean the message was delivered?
No. ESME_ROK on submit_sm_resp only confirms the SMSC accepted the message for processing. Final delivery to the handset is reported later in the delivery receipt (deliver_sm), which carries its own status such as DELIVRD, UNDELIV or EXPIRED. Always reconcile submit acceptance against the DLR.
Which SMPP errors are safe to retry?
Transient, system-side codes are retryable with backoff: ESME_RSYSERR (0x08), ESME_RMSGQFUL (0x14), ESME_RTHROTTLED (0x58), ESME_RSUBMITFAIL (0x45) and ESME_RUNKNOWNERR (0xFF). Validation errors such as invalid addresses, TON/NPI, message length or bad credentials are permanent — fix the request or configuration instead of retrying.
Are these codes the same across all SMSCs?
The 0x00000000–0x000000FF codes are defined by the SMPP v3.4 spec and are consistent across compliant SMSCs. Ranges 0x00000400–0x000004FF are reserved for vendor-specific errors, so a given SMSC may return additional codes there with its own meanings — always check your provider's documentation for those.
Binding an SMPP session?
BroadNet offers direct SMPP 3.4 binds with predictable throughput and clear command_status handling. Talk to our team about a connection.