SMS Delivery Reports, Error Codes & Failed Message Checks

Start with the message ID and the stage of failure

Separate three events: your application requested a send, the provider accepted it, and a delivery receipt arrived. An HTTP success response or an SMPP submission acknowledgement does not by itself prove that the destination received the SMS.

Store the provider message ID beside your own business-event ID. A campaign reference alone may cover thousands of individual messages. The outbound status lifecycle illustrates why submission and delivery must be tracked separately.

Read the status before interpreting an error code

Dashboards can rename statuses. Preserve the original value as well as your internal category. For multipart SMS, also check whether the report describes a segment or the complete logical message — a longer message's segment count is easy to check with the SMS character and segment counter.

Standard SMPP response codes: examples, not a carrier DLR dictionary

The following hexadecimal values belong to SMPP command_status. They must not be used to decode a similarly numbered provider API error or the err field inside a delivery receipt. They are also distinct from the numeric code values returned by MetaReach's own Send SMS and DLR API, which use a separate 001–011 scheme documented there.

The SMPP specification, section 5.1.3 and Appendix B, distinguishes command responses from delivery receipt errors. DLR error meanings are network or SMSC specific. Obtain the dictionary for the exact MetaReach route or API version you use — see SMPP vs HTTP SMS API if you're still choosing between the two integration methods.

Investigate a failed India SMS in a consistent order

1. Request: check required fields, credentials, balance and enabled route against your account documentation.
2. Destination: verify the expected number format and remove accidental spaces or duplicate country prefixes.
3. Sender and template: compare the approved header, entity/template identifiers and final text with the configured request — see DLT SMS template examples for how to draft and map that content.
4. Variables and encoding: check substituted values, punctuation, invisible characters and message length.
5. Receipt: retain the complete error, timestamp and source field. Ask support whether the rejection came from the API, SMSC, DLT check or destination network.

These checks identify what to investigate; they do not assign a universal cause to every failed SMS. For template preparation use DLT template examples, DLT registration support and the existing PE–TM binding guide.

Avoid duplicate sends while fixing delivery

Classify the failure before deciding to retry. A malformed destination needs correction. A rate-limit response calls for pacing. A timed-out request has an uncertain submission outcome and needs reconciliation.

Use a stable business-event identifier and the provider's documented deduplication mechanism where available. Keep bounded retry attempts and expiry rules. A delayed receipt should not restart the original campaign. For an expired OTP, follow the product's fresh-code flow instead of sending an old credential.

Callback handlers should authenticate requests using the provider's documented method, record the event durably and tolerate repeats. Review your state transitions so a late pending event cannot overwrite a confirmed final result.

Send support a useful diagnostic record

Provide the campaign reference, provider message ID, masked destination, send time with timezone, sender/header, template ID, latest raw status, raw error and whether one or many recipients are affected. Keep credentials and live OTPs out of the ticket.

Compare a small successful sample with the failed sample from the same period. Differences in message text, route or sender are more useful than repeatedly resending the whole list.

For setup questions, explore SMS API integration, the full SMS API documentation, or SMPP connectivity. If you need to review the overall sending setup, start with MetaReach Bulk SMS services.

Frequently asked questions