When an SMS submission fails, the SMSC does not send a vague warning. It returns a specific 32 bit status value in the response PDU, and that value tells you what went wrong. Those values are SMPP error codes. Read them correctly and a failed bind or a rejected message takes minutes to fix instead of days.
This guide lists every error code defined in SMPP v3.4, explains what each one means in practice, and shows how to fix the ones you will meet most often. It also covers a point that trips up many teams: the codes in delivery receipts are a different thing.
Quick Answer
SMPP error codes are hexadecimal values returned in the command_status field of an SMPP response PDU. A value of 0x00000000 means success. Any other value signals a failure, such as a bad password (0x0E), a throttled connection (0x58), or an invalid destination (0x0B). Each code points to a specific cause and fix.
Key Takeaways
- The command_status field in every PDU response carries the error code. 0x00000000 (ESME_ROK) is the only success value.
- Most production incidents come from a small group: 0x0D, 0x0E, 0x04, 0x08, 0x0B, 0x14, 0x45, and 0x58.
- Throttling (0x58) and queue full (0x14) are signals to slow down, not to retry harder.
- Delivery receipt error codes are operator specific and are not part of the SMPP command_status table.
- Always log the full PDU, sequence number and system_id when an error occurs. The code alone rarely finds the root cause.
What Are SMPP Error Codes?
Short Message Peer to Peer (SMPP) is a protocol that lets an External Short Message Entity (ESME), such as an application or aggregator platform, exchange SMS traffic with a Short Message Service Center (SMSC). Every request the ESME sends gets a response, and every response carries a command_status value.
SMPP error codes are the non zero values of that field. They are defined in the SMPP v3.4 specification published by the SMS Forum, and most SMSC vendors follow the same table. Some vendors add custom codes in the range reserved for vendor use, so check your SMSC documentation if you see a value that is not listed below.
How to Read an SMPP Error Response
An SMPP response PDU has a 16 byte header with four fields: command_length, command_id, command_status and sequence_number. The error code lives in command_status.
Take a rejected message as an example. Your ESME sends a submit_sm with sequence number 42. The SMSC replies with a submit_sm_resp, sequence number 42, and command_status 0x0000000B. The matching sequence number tells you which submission failed. The status tells you the destination address was invalid.
Two habits make this easier. First, always match the response to the request by sequence number, because responses can arrive out of order on a busy session. Second, log the code in hex and as its symbolic name (ESME_RINVDSTADR) so support teams on both sides read it the same way.
SMPP Error Codes: Full List
The tables below group codes by this kind of problem. The Fix column gives the first thing to check.
Session and Bind Errors
| Hex | Name | Meaning | First fix |
| 0x04 | ESME_RINVBNDSTS | Command sent in the wrong bind state | Bind before submitting; check bind type matches the command |
| 0x05 | ESME_RALYBND | ESME is already bound | Close the old session or avoid a second bind on the same connection |
| 0x0D | ESME_RBINDFAIL | Bind failed | Check IP whitelist, port, system_type and account status |
| 0x0E | ESME_RINVPASWD | Invalid password | Confirm the password and character case with the SMSC admin |
| 0x0F | ESME_RINVSYSID | Invalid system_id | Confirm the exact system_id issued to you |
PDU Format and Command Errors
| Hex | Name | Meaning | First fix |
| 0x01 | ESME_RINVMSGLEN | Message length invalid | Check short_message length against sm_length |
| 0x02 | ESME_RINVCMDLEN | Command length invalid | Recalculate command_length for the full PDU |
| 0x03 | ESME_RINVCMDID | Invalid command ID | Verify the command_id is valid for your SMPP version |
| 0x06 | ESME_RINVPRTFLG | Invalid priority flag | Use only the priority values the SMSC supports |
| 0x07 | ESME_RINVREGDLVFLG | Invalid registered delivery flag | Correct the registered_delivery bits |
| 0x43 | ESME_RINVESMCLASS | Invalid esm_class | Check UDH and message mode bits |
| 0x53 | ESME_RINVSYSTYP | Invalid system_type | Match the value the SMSC expects, or leave it empty |
Address and Routing Errors
| Hex | Name | Meaning | First fix |
| 0x0A | ESME_RINVSRCADR | Invalid source address | Check sender ID format, length and approval |
| 0x0B | ESME_RINVDSTADR | Invalid destination address | Use correct MSISDN format and country code |
| 0x48 | ESME_RINVSRCTON | Invalid source TON | Set the correct type of number |
| 0x49 | ESME_RINVSRCNPI | Invalid source NPI | Set the correct numbering plan indicator |
| 0x50 | ESME_RINVDSTTON | Invalid destination TON | Align TON with the number format used |
| 0x51 | ESME_RINVDSTNPI | Invalid destination NPI | Align NPI with the number format used |
| 0x15 | ESME_RINVSERTYP | Invalid service_type | Use a service type the SMSC has provisioned |
Submission, Queue and Throttling Errors
| Hex | Name | Meaning | First fix |
| 0x08 | ESME_RSYSERR | System error at the SMSC | Retry with backoff; escalate if it persists |
| 0x14 | ESME_RMSGQFUL | Message queue full | Slow submission; ask the SMSC about queue limits |
| 0x45 | ESME_RSUBMITFAIL | submit_sm or submit_multi failed | Inspect the message content and route; check SMSC logs |
| 0x58 | ESME_RTHROTTLED | Throttling error | Reduce TPS to the agreed window and back off |
| 0x33 | ESME_RINVNUMDESTS | Invalid number of destinations | Keep submit_multi within the allowed destination count |
| 0x34 | ESME_RINVDLNAME | Invalid distribution list name | Use a provisioned list |
| 0x40 | ESME_RINVDESTFLAG | Invalid destination flag in submit_multi | Set the flag to address or list correctly |
| 0x44 | ESME_RCNTSUBDL | Cannot submit to distribution list | Check permissions for the list |
Message Management Errors
| Hex | Name | Meaning | First fix |
| 0x0C | ESME_RINVMSGID | Invalid message ID | Use the exact message_id from submit_sm_resp |
| 0x11 | ESME_RCANCELFAIL | cancel_sm failed | Message may already be delivered or expired |
| 0x13 | ESME_RREPLACEFAIL | replace_sm failed | Check message_id and source address match |
| 0x42 | ESME_RINVSUBREP | Invalid submit with replace request | Review replace_if_present usage |
| 0x54 | ESME_RINVREPFLAG | Invalid replace_if_present flag | Send 0 or 1 only |
| 0x55 | ESME_RINVNUMMSGS | Invalid number of messages | Correct the value in query or cancel requests |
| 0x61 | ESME_RINVSCHED | Invalid scheduled delivery time | Use the correct time format |
| 0x62 | ESME_RINVEXPIRY | Invalid validity period | Use the correct time format and a future value |
| 0x63 | ESME_RINVDFTMSGID | Predefined message not found | Use a provisioned message ID |
| 0x67 | ESME_RQUERYFAIL | query_sm failed | Confirm the message_id and source address |
Optional Parameter and Application Errors
| Hex | Name | Meaning | First fix |
| 0x64 | ESME_RX_T_APPN | Receiver temporary application error | Retry later; fix the receiving application |
| 0x65 | ESME_RX_P_APPN | Receiver permanent application error | Do not retry; fix the receiving application |
| 0x66 | ESME_RX_R_APPN | Receiver rejected the message | Review message content and receiver rules |
| 0xC0 | ESME_RINVOPTPARSTREAM | Error in the optional part of the PDU | Validate TLV encoding and order |
| 0xC1 | ESME_ROPTPARNOTALLWD | Optional parameter not allowed | Remove the TLV from that command |
| 0xC2 | ESME_RINVPARLEN | Invalid parameter length | Fix the TLV length field |
| 0xC3 | ESME_RMISSINGOPTPARAM | Expected optional parameter missing | Add the required TLV |
| 0xC4 | ESME_RINVOPTPARAMVAL | Invalid optional parameter value | Correct the TLV value |
| 0xFE | ESME_RDELIVERYFAILURE | Delivery failure (data_sm_resp) | Check the route and handset state |
| 0xFF | ESME_RUNKNOWNERR | Unknown error | Capture the PDU and escalate to the SMSC team |
Codes 0x65 and 0x66 are worth a note. They are mainly relevant when the SMSC delivers a message to your ESME and your application responds with an error, so the fault sits on your receiving side.
How to Fix the Most Common SMPP Error Codes
0x0D and 0x0E: Bind Failures
A bind failure almost always comes from credentials or network rules. Check four things in order: the system_id, the password (case sensitive on most SMSCs), the source IP against the SMSC whitelist, and the bind type your account allows (transmitter, receiver or transceiver). A hypothetical example: an aggregator moves its platform to a new data center, the public IP changes, and every bind returns 0x0D until the provider updates the whitelist. If credentials are correct and the IP is approved, ask the SMSC team whether the account is locked after repeated failed attempts.
0x04: Incorrect Bind State
This appears when you send a command your bind type does not permit, for example a submit_sm on a receiver only session. It also appears when a command arrives before the bind completes. Wait for bind_resp with status 0x00000000, then send traffic. Check that your connection pool does not hand out sessions that are still binding.
0x58: Throttling
The SMSC is telling you that you exceeded the submission rate allowed on your account. Do not retry immediately. Retrying at full speed keeps you throttled. Apply exponential backoff, cap your TPS to the agreed limit, and use a windowed send limit with the in flight window size your provider specifies. If you need more capacity, request a higher limit instead of working around the cap.
0x14: Message Queue Full
The SMSC queue for your account or route cannot take more messages. Pause submission, let the queue drain, and resume at a lower rate. Frequent 0x14 responses usually point to a downstream route that is slow, so ask your provider whether delivery on that route is delayed.
0x0A and 0x0B: Bad Source or Destination Address
Check the number format first. Use a full international format and set TON and NPI to match. For a source address, confirm the sender ID is registered where the destination country requires it. Several markets in the target regions for this article, including parts of the UAE, India and the US, apply sender or template rules that can cause rejection even when the PDU is technically valid. Verify country specific sender ID rules with the relevant regulator before publishing.
0x08 and 0x45: System Error and Submit Failure
These codes are broad. 0x08 usually reflects a temporary fault at the SMSC. 0x45 often reflects a content or route problem. Retry a small number of times with backoff, then look at whether failures cluster by destination country, sender ID or message content. Clusters point to a route or filter. Random spread points to an SMSC fault.
A Triage Order That Saves Time
Work from the cheapest check to the most expensive.
- Identify the code and the command: A 0x0B on bind_resp is impossible, so confirm which PDU returned it.
- Check your own side first: Credentials, bind type, TON and NPI, PDU lengths and encoding.
- Check session health: Confirm enquire_link is flowing in both directions so you are not working with a half dead session.
- Check your rate: Compare actual TPS against your agreed limit.
- Isolate by dimension: Split failures by destination country, sender ID, message content and time of day.
- Escalate with evidence: Send the SMSC team the PDU hex dump, timestamps, system_id and sequence numbers.
SMPP Error Codes vs Delivery Receipt Errors
A command_status error means the SMSC refused your request. A delivery receipt (DLR) reports what happened after the SMSC accepted the message. These are separate mechanisms.
A DLR is delivered as a deliver_sm and usually carries a text body with fields such as stat (for example DELIVRD, UNDELIV or EXPIRED) and err. The error value is generally operator or SMSC specific and does not map to the table above. Your provider’s documentation defines it, and it can differ between routes. Treat a submit_sm_resp with status 0x00000000 as “accepted for processing”, not as “delivered”.
Common Mistakes to Avoid
- Retrying throttled traffic at full speed: This extends the throttle. Back off instead.
- Treating every error as retryable: Permanent errors such as 0x0B or 0x0E will not succeed on a second attempt.
- Ignoring sequence numbers: Without them you cannot tell which message failed.
- Skipping enquire_link: Silent session drops look like random submission failures.
- Confusing DLR err values with command_status codes: They come from different layers.
- Logging only the code: Keep the full PDU so your provider can trace it.
Conclusion
SMPP error codes are precise signals. The command_status value tells you whether the problem sits in your session, your PDU, your addressing, your rate or the SMSC itself, and the triage order above turns that signal into a fix. Keep full PDU logs, treat throttling as a limit to respect, and never mix command_status errors with DLR error values.
Operators who bridge SMPP traffic into signaling networks face an extra layer of failure points, because errors can originate on either side of the conversion. If that describes your setup, the TeleOSS SMPP2SIGTRAN Converter is worth evaluating for connecting SMPP based messaging systems to SIGTRAN based core networks. Review the product page or contact the team to discuss your architecture and the error handling you need.
FAQs
What does ESME_ROK mean in SMPP?
ESME_ROK is the symbolic name for 0x00000000, which means the request was processed without error. It is the only success status in the command_status field. It confirms the SMSC accepted the request, not that the handset received the message.
What is SMPP error 0x58?
0x58 is ESME_RTHROTTLED. The SMSC rejected the request because you exceeded your permitted submission rate. Reduce your TPS to the agreed limit, retry with exponential backoff, and ask your provider for a higher limit if your traffic needs it.
What causes SMPP bind failure 0x0D?
ESME_RBINDFAIL is a general bind failure. Common causes are an IP address not on the SMSC whitelist, a wrong port, an unsupported bind type, a locked account or a system_type mismatch. Check network access first, then account status with the SMSC team.
How do I tell a temporary SMPP error from a permanent one?
Temporary errors, such as 0x08, 0x14 and 0x58, can succeed on retry after a delay. Permanent errors, such as 0x0B, 0x0E and 0x0F, will fail again until you change the request or the account setup. Retry only the first group.
Are SMPP error codes the same across all SMSCs?
The core values come from the SMPP v3.4 specification and are widely shared. Vendors can add custom codes, and DLR error values are vendor or operator specific. Always compare an unfamiliar code against your SMSC vendor’s documentation.
Where do I find the full SMPP error code list?
The authoritative source is the SMPP v3.4 specification from the SMS Forum, which defines the command_status table. The list in this article follows that table, grouped by problem type for faster troubleshooting.