TeleOSS

SMPP Error Codes: Full List and How to Fix Each

  • November 20, 2026
  • Posted By: TeleOSS
ASK AI ABOUT THIS BLOG
SMPP Error Codes: Full List and How to Fix Each

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

HexNameMeaningFirst fix
0x04ESME_RINVBNDSTSCommand sent in the wrong bind stateBind before submitting; check bind type matches the command
0x05ESME_RALYBNDESME is already boundClose the old session or avoid a second bind on the same connection
0x0DESME_RBINDFAILBind failedCheck IP whitelist, port, system_type and account status
0x0EESME_RINVPASWDInvalid passwordConfirm the password and character case with the SMSC admin
0x0FESME_RINVSYSIDInvalid system_idConfirm the exact system_id issued to you

PDU Format and Command Errors

HexNameMeaningFirst fix
0x01ESME_RINVMSGLENMessage length invalidCheck short_message length against sm_length
0x02ESME_RINVCMDLENCommand length invalidRecalculate command_length for the full PDU
0x03ESME_RINVCMDIDInvalid command IDVerify the command_id is valid for your SMPP version
0x06ESME_RINVPRTFLGInvalid priority flagUse only the priority values the SMSC supports
0x07ESME_RINVREGDLVFLGInvalid registered delivery flagCorrect the registered_delivery bits
0x43ESME_RINVESMCLASSInvalid esm_classCheck UDH and message mode bits
0x53ESME_RINVSYSTYPInvalid system_typeMatch the value the SMSC expects, or leave it empty

Address and Routing Errors

HexNameMeaningFirst fix
0x0AESME_RINVSRCADRInvalid source addressCheck sender ID format, length and approval
0x0BESME_RINVDSTADRInvalid destination addressUse correct MSISDN format and country code
0x48ESME_RINVSRCTONInvalid source TONSet the correct type of number
0x49ESME_RINVSRCNPIInvalid source NPISet the correct numbering plan indicator
0x50ESME_RINVDSTTONInvalid destination TONAlign TON with the number format used
0x51ESME_RINVDSTNPIInvalid destination NPIAlign NPI with the number format used
0x15ESME_RINVSERTYPInvalid service_typeUse a service type the SMSC has provisioned

Submission, Queue and Throttling Errors

HexNameMeaningFirst fix
0x08ESME_RSYSERRSystem error at the SMSCRetry with backoff; escalate if it persists
0x14ESME_RMSGQFULMessage queue fullSlow submission; ask the SMSC about queue limits
0x45ESME_RSUBMITFAILsubmit_sm or submit_multi failedInspect the message content and route; check SMSC logs
0x58ESME_RTHROTTLEDThrottling errorReduce TPS to the agreed window and back off
0x33ESME_RINVNUMDESTSInvalid number of destinationsKeep submit_multi within the allowed destination count
0x34ESME_RINVDLNAMEInvalid distribution list nameUse a provisioned list
0x40ESME_RINVDESTFLAGInvalid destination flag in submit_multiSet the flag to address or list correctly
0x44ESME_RCNTSUBDLCannot submit to distribution listCheck permissions for the list

Message Management Errors

HexNameMeaningFirst fix
0x0CESME_RINVMSGIDInvalid message IDUse the exact message_id from submit_sm_resp
0x11ESME_RCANCELFAILcancel_sm failedMessage may already be delivered or expired
0x13ESME_RREPLACEFAILreplace_sm failedCheck message_id and source address match
0x42ESME_RINVSUBREPInvalid submit with replace requestReview replace_if_present usage
0x54ESME_RINVREPFLAGInvalid replace_if_present flagSend 0 or 1 only
0x55ESME_RINVNUMMSGSInvalid number of messagesCorrect the value in query or cancel requests
0x61ESME_RINVSCHEDInvalid scheduled delivery timeUse the correct time format
0x62ESME_RINVEXPIRYInvalid validity periodUse the correct time format and a future value
0x63ESME_RINVDFTMSGIDPredefined message not foundUse a provisioned message ID
0x67ESME_RQUERYFAILquery_sm failedConfirm the message_id and source address

Optional Parameter and Application Errors

HexNameMeaningFirst fix
0x64ESME_RX_T_APPNReceiver temporary application errorRetry later; fix the receiving application
0x65ESME_RX_P_APPNReceiver permanent application errorDo not retry; fix the receiving application
0x66ESME_RX_R_APPNReceiver rejected the messageReview message content and receiver rules
0xC0ESME_RINVOPTPARSTREAMError in the optional part of the PDUValidate TLV encoding and order
0xC1ESME_ROPTPARNOTALLWDOptional parameter not allowedRemove the TLV from that command
0xC2ESME_RINVPARLENInvalid parameter lengthFix the TLV length field
0xC3ESME_RMISSINGOPTPARAMExpected optional parameter missingAdd the required TLV
0xC4ESME_RINVOPTPARAMVALInvalid optional parameter valueCorrect the TLV value
0xFEESME_RDELIVERYFAILUREDelivery failure (data_sm_resp)Check the route and handset state
0xFFESME_RUNKNOWNERRUnknown errorCapture 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.

  1. Identify the code and the command: A 0x0B on bind_resp is impossible, so confirm which PDU returned it.
  2. Check your own side first: Credentials, bind type, TON and NPI, PDU lengths and encoding.
  3. Check session health: Confirm enquire_link is flowing in both directions so you are not working with a half dead session.
  4. Check your rate: Compare actual TPS against your agreed limit.
  5. Isolate by dimension: Split failures by destination country, sender ID, message content and time of day.
  6. 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.

Contact Us
WhatsApp Email Call Text
Thank you! You will receive an email shortly and the download will start.