Delivery Report Reason Codes

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

This page documents the types of delivery report which can be returned by the MX Telecom SMS Gateway, as well as the possible values for the Detailed Reason Code field.

An overview of delivery report interpretation can be found here.

Contents

Types of delivery report

The following delivery report types may be returned by the SMS Gateway:

TypeDescription
REJECTEDIf a message or billing request is not accepted by the carrier, the SMS Gateway may make several more attempts to submit the message, according to a retry strategy. If the message still has not been accepted once the retry strategy is complete (or immediately, in the case of permanent errors such as invalid destination), a REJECTED report is returned.
BUFFEREDBuffered means that the message has reached a particular stage in its processing. It is not final confirmation of delivery OR failure (although they are sometimes used to confirm billing has been successful).
FAILEDFailed means that the message has been failed after it was submitted to the carrier for delivery.
DELIVEREDDelivered means that the message has been successfully delivered to the handset, including billing the subscriber where this is separate.

Detailed reason codes

The detailed reason code gives more information about the reason for the delivery notification, such as the error which prevented delivery of a message, whether billing has been successful, and so on.

The four bytes making up the reason code can be broken down as follows:

Most significant byte Reason byte Reason byte 2 Network byte
Type nibble Billing nibble
0x1 REJECTED 0x0 See below Varies according to type 0x00 No information
0x3 BUFFERED 0x1 Post billing   0x10 On net
0x5 FAILED 0x2 New subscription 0x11 Virgin Mobile UK
0x6 DELIVERED 0x4 Message submitted 0x12 MVNO
  0x20 Alltel user ported to Verizon
  • The Type nibble corresponds directly to the delivery report type. Values other than those defined in the table are reserved, and applications should ignore any delivery reports with an unrecognized type.
  • The Billing nibble is a bitmask which gives information on the billing status of a premium message.
    • The billing nibble may be set to 1 on REJECTED, BUFFERED or FAILED reports to indicate that the subscriber has been successfully charged, even though the message contents themselves may not have been delivered. The billing nibble will never be set to 1 when a message is billed using a carrier-managed subscription (see below).
    • The billing nibble may be set to 2 on any kind of report (including DELIVERED reports) to indicate that a new carrier-managed subscription mandate was created while attempting to deliver the message, and the subscriber has been successfully charged. This is only set if the carrier manages the subscription themselves (eg, on AT&T USA).
    • The billing nibble may be set to 4 on a REJECTED or FAILED report to indicate that although the billing transaction failed, the message was submitted to the carrier for delivery. This will only happen on carriers where billing happens after submission, indicating that although the message was sent to the subscriber, the subscriber could not be subsequently billed.
    • On a REJECTED, BUFFERED or FAILED report, if neither the post-billing nor the new subscription bit is set, it indicates that the subscriber has not been charged. Note that, for historical reasons, the post-billing nibble is not always set on DELIVERED reports; however a DELIVERED report for a premium MT message always implies that the subscriber has been successfully charged.
  • The Reason bytes give more detail on the reason for the delivery notification. Their meaning varies according to the type of report; see the tables below for further information.
  • The Network byte gives information on the carrier of the subscriber. In most cases, this is not available, and this byte will be set to zero; however on some carriers, the message-submission interface returns an indication of whether the subscriber was "on-net" or on a virtual network. In this case, the Network byte will be set to 0x10 for "on-net", 0x11 if the subscriber was on the Virgin Mobile UK carrier, or 0x12 if the subscriber was on an unknown MVNO. Other values are reserved for other MVNOs and applications should treat unrecognized values in the same way as a value of 0x00.

Reason byte tables

The following tables define the possible values for the Reason bytes within the delivery report reason code. The Billing nibble and Network byte do not form part of this interpretation, so are represented by the character ‘.’ to indicate that they may take any value.

Reason bytes which are not defined in the tables below are reserved for future expansion. REJECTED and FAILED delivery reports are divided into groups, and thus if an application receives a reason code which it does not understand, it should ignore the less significant parts of the reason code and look for a reason code group which is recognized. In any case, the Type and Billing Nibbles alone will normally provide enough information for correct operation of applications.

0x1....... - REJECTED

For REJECTED delivery reports, the reason bytes give more information on why the message was not accepted by the carrier. The table below defines the possible values for the reason bytes, and also documents the retry strategy which will have been used to resubmit the message to the carrier before giving up and returning the REJECTED delivery report. Reason code groups are highlighted in dark blue.

Hexadecimal reason code Symbolic name Description Retry strategy Notes
  0x1.0000.. REASON_REJECTED Unknown error General An unexpected error occurred during delivery, where we cannot differentiate between a system failure (some part of system not functioning correctly) and an expected failure (unknown subscriber, etc).
  0x1.0004.. REASON_REJECTED_EXPIRED Message expired Fail The message exceeded its validity period before a delivery attempt could be made.
0x1.010...   Reason code group: generic billing error   Group of billing-related errors which do not fit into any of the other billing groups below.
  0x1.0100.. REASON_REJECTED_BILLING Billing failed (generic) Billing An unexpected error occurred during billing, where we cannot differentiate between a system failure (some part of system not functioning correctly) and an expected failure (subscriber out of credit, etc).
  0x1.0101.. REASON_REJECTED_BILLING_PREPAYUNSUP Prepay billing unsupported Fail Billing of prepay subscribers is not supported on this carrier.
  0x1.0102.. REASON_REJECTED_BILLING_PSMSBARRED MT charge barred (generic) Fail Charges to this subscriber have been barred - no further information available from carrier.
0x1.011...   Reason code group: charge failed Fail Group of billing-related errors: this particular charge has been rejected, but the subscriber is still billable.
  0x1.0110.. REASON_REJECTED_BILLING_CHARGEFAILED Charge failed Fail This charge has been rejected by the carrier. Used where none of the reasons below apply, but we believe that the subscriber is still billable (unlike REASON_REJECTED_BILLING_PSMSBARRED).
  0x1.0111.. REASON_REJECTED_BILLING_OPTINEXPIRED No carrier-controlled opt-in confirmation received Fail On carriers where the carrier controls an opt-in process (eg, AT&T ACM), this reason code is returned if no positive opt-in is received within the timelimit allowed by the carrier, e.g. if the PIN has expired (the with-PIN workflow) or the opportunity to reply "Y" has expired (the without-PIN workflow).
  0x1.0112.. REASON_REJECTED_BILLING_MANDATE_TERMINATED Subscription billing mandate has been terminated Fail A previously-active subscription billing mandate has now terminated. No further billing should be performed under this subscription.
  0x1.0113.. REASON_REJECTED_BILLING_MANDATE_EXCEEDED Charge exceeds terms of subscription billing mandate Fail This charge exceeds the terms (eg, monthly limit) of a subscription billing mandate.
  0x1.0114.. REASON_REJECTED_BILLING_ACTIVE_OPTIN Previous opt-in process still active Fail On carriers where the carrier controls the opt-in process (e.g., AT&T or Verizon), this reason code is returned if there is already a pending opt-in process for this subscription.
  0x1.0115.. REASON_REJECTED_BILLING_CONSENT_NOT_SUPPORTED Carrier is not AT&T or Verizon Fail Returned when an AT&T ACM request or a Verizon consent management request is sent to the wrong carrier.
  0x1.0116.. REASON_REJECTED_BILLING_OPTINBLOCKED AT&T ACM opt in attempted too many times Fail Returned for AT&T ACM requests only. If you submit a single-item or subscription purchase request with a PIN for the same mobile phone number, short code, and program ID and the PIN verification fails five times in a row, all subsequent verification attempts for the mobile phone number, short code, and program ID are blocked for a period of 30 minutes.
  0x1.0117.. REASON_REJECTED_BILLING_PININVALID PIN incorrect for AT&T ACM request Fail Returned for AT&T ACM requests only. The PIN returned as part of the ACM workflow does not match the PIN sent to the end user. The correct PIN has yet to expire, so you can ask that the end user re-enters the PIN and then retry this request with the new PIN details.
0x1.012...   Reason code group: credit control Billing Group of billing-related errors: subscriber has reached a credit/spending limit.
  0x1.0120.. REASON_REJECTED_BILLING_SPENDCAP_OR_OUTOFCREDIT Over spend limit or out of credit Billing Subscriber has reached a spending limit, or is out of credit. Used when we cannot distinguish which.
  0x1.0121.. REASON_REJECTED_BILLING_SPENDCAP Subscriber has reached spending limit Billing Subscriber has reached a spending limit (eg, monthly spend cap).
  0x1.0122.. REASON_REJECTED_BILLING_OUTOFCREDIT Subscriber out of credit Billing Subscriber has exceeded their credit limit. This is specific to limits which can be resolved by the subscriber adding credit to their account. Note that this may apply to either pre or postpay subscribers.
0x1.013...   Reason code group: problem billing subscriber account Fail Group of billing-related errors: there is a problem billing this subscriber.
  0x1.0131.. REASON_REJECTED_BILLING_ACCOUNT_CLOSED Account closed Fail Attempt to bill against a closed account. This subscriber should not be billed further.
  0x1.0132.. REASON_REJECTED_BILLING_ACCOUNT_LOCKED Account locked Fail Attempt to bill against a locked/suspended account.
  0x1.0133.. REASON_REJECTED_BILLING_BARRED_RESELLER Billing barred (reseller settings) Fail Subscriber obtains connectivity via a reseller; billing of this subscriber is therefore barred.
  0x1.0134.. REASON_REJECTED_BILLING_BARRED_ADULT Billing barred (adult) Fail Adult settings on subscriber account prevent billing of subscriber.
0x1.02....   Reason code group: source   Group of error codes indicating there was a problem with the message originator.
  0x1.0200.. REASON_REJECTED_SOURCE Invalid source address Fail Originator on this message was invalid.
  0x1.0201.. REASON_REJECTED_SOURCE_NOTPROVISIONED Provisioning error General Shortcode has not been provisioned. Contact MX Telecom support.
  0x1.0202.. REASON_REJECTED_SOURCE_NOTPROVISIONEDTESTONLY Provisioned for testing only Fail An attempt was made to send a message to an unwhitelisted subscriber from a shortcode which has only been provisioned for testing.
0x1.03....   Reason code group: destination temporary Fail Group of error codes indicating a non-permanent problem with the destination (later traffic to this destination may succeed).
  0x1.0300.. REASON_REJECTED_DESTTEMP Invalid destination Fail Temporary delivery problem to the destination.
  0x1.0301.. REASON_REJECTED_DESTTEMP_BARRED Barred Fail Temporary bar on delivery of this content to the destination.
  0x1.0302.. REASON_REJECTED_DESTTEMP_SIMFULL SIM full Fail Message could not be delivered as handset message memory is full.
  0x1.0303.. REASON_REJECTED_DESTTEMP_ABSENT Subscriber absent Fail Message could not be delivered as handset is absent from the carrier.
  0x1.0304.. REASON_REJECTED_DESTTEMP_DELIVFAIL Delivery failed Fail Temporary delivery problem to the destination.
0x1.04....   Reason code group: destination permanent Fail Group of error codes representing a permanent problem with the destination (destination should be removed from subscriber list).
  0x1.0400.. REASON_REJECTED_DESTPERM Invalid destination Fail Delivery to this subscriber has failed for an unknown reason. It may be due to a premium-rate bar, so it may still be possible to deliver standard-rate messages to this subscriber after failure of a premium message.
  0x1.0401.. REASON_REJECTED_DESTPERM_BARRED Barred Fail Delivery to this subscriber has been barred.
  0x1.0402.. REASON_REJECTED_DESTPERM_NOSMS All SMS barred Fail This subscriber cannot receive bulk or premium SMS messages from any sender
  0x1.0405.. REASON_REJECTED_DESTPERM_UNKNOWNSUB Unknown subscriber Fail The destination of this message does not represent a known subscriber. For billing traffic, or traffic within the USA, this may be carrier specific - i.e. the subscriber may be known by another carrier. For non-USA bulk messages it means the number is invalid.
  0x1.0406.. REASON_REJECTED_DESTPERM_PORTED Ported off-net Fail This subscriber is known to have ported off-net; delivery through this carrier is no longer possible.
  0x1.0407.. REASON_REJECTED_DESTPERM_RESELLER Delivery barred (reseller settings) Fail Subscriber obtains connectivity via a reseller; messaging to this subscriber is therefore barred.
  0x1.0408.. REASON_REJECTED_DESTPERM_MVNO Delivery barred (MVNO settings) Fail Subscriber obtains connectivity via a virtual carrier (MVNO); messaging to this subscriber is therefore barred.
0x1.05....   Reason code group: system error General Group of errors representing an unexpected error when processing the message.
  0x1.0500.. REASON_REJECTED_SYSFAIL System error General Some part of MX Telecom or carrier systems not functioning correctly. Contact MX Telecom support for more details.
  0x1.0501.. REASON_REJECTED_SYSFAIL_BILLING System error during billing General As per REASON_REJECTED_SYSFAIL, for errors occuring during billing phase.
0x1.06....   Reason code group: message Fail Group of error codes representing a problem with the message content.
  0x1.0600.. REASON_REJECTED_MSG Bad message Fail Carrier rejected message contents. Used where we have no further information as to the problem with the contents.
  0x1.0601.. REASON_REJECTED_MSG_UNICODE Unicode not supported Fail Unicode (UCS2) messages are not supported on this carrier/shortcode.
  0x1.0602.. REASON_REJECTED_MSG_BINARY Binary not supported Fail Binary (8-bit) messages are not supported on this carrier/shortcode.
  0x1.0603.. REASON_REJECTED_MSG_OPTIN Invalid opt-in Fail Message could not be submitted to carrier due to invalid opt-in details

0x3....... - BUFFERED

BUFFERED reports indicate that a message has reached a particular stage in its processing; the reason bytes therefore describe what has just taken place.

Hexadecimal reason code Symbolic name Description Notes
0x3.0000.. REASON_BUFFERED Buffered for unknown reason This reason code is returned when we receive a notification from the carrier that they have been unable to deliver the message, but are continuing to retry.
0x310001.. REASON_BUFFERED_BILLING_SUCCESSFUL Billing succeeded Indicates that the message was successfully billed. Note that the Billing nibble will always be set to 1 with this reason code.
0x3.0100.. REASON_BUFFERED_BILLING Buffered whilst awaiting a billing action  
0x3.0103.. REASON_BUFFERED_BILLING_PENDING_OPTIN Buffered whilst awaiting subscriber opt-in The message is being held whilst the carrier performs an opt-in process (eg, AT&T USA OPPC).
0x3.03....   Reason code group: destination temporary Temporary delivery problem to the destination.
0x3.0302.. REASON_BUFFERED_DESTTEMP_SIMFULL SIM full Message could not be delivered as handset message memory is full.
0x3.0303.. REASON_BUFFERED_DESTTEMP_ABSENT Subscriber absent Message could not be delivered as handset is absent from the carrier.
0x3.0304.. REASON_BUFFERED_DESTTEMP_DELIVFAIL Delivery failed Temporary delivery problem to the destination.

0x5....... - FAILED

The reason bytes for FAILED delivery reports give more information on why the carrier was unable to deliver the message after accepting it. The possible values are the same as those for REJECTED, except that they begin with 5 rather than 1. For instance, REASON_FAILED_DESTPERM is 0x50040000.

0x6....... - DELIVERED

The table below gives the reason bytes which can be associated with DELIVERED delivery reports. Note that, for historical reasons, the Billing nibble of DELIVERED reports may be set to zero; however, a DELIVERED report for a premium MT message always implies that the subscriber has been succesfully charged.

Hexadecimal reason code Symbolic name Description Notes
0x6.0000.. REASON_DELIVERED Message delivered to subscriber Message delivered to handset.
0x620000.. REASON_DELIVERED_NEW_SUBSCRIPTION Delivered, with a new subscription initiated. Message delivered to handset. As part of the billing process, a new carrier-managed subscription billing mandate was created with the user's carrier.
0x6.0002.. REASON_DELIVERED_FAKEMT Fake MT message processed. Control message (eg, STOP MT for subscription termination) has been processed.

Examples

Below are some examples of reason codes, and their interpretations:

Report type Reason code
(decimal)
Reason code
(hexadecimal)
Symbolic name Meaning
DELIVERED 1610612736 0x60000000 REASON_DELIVERED Delivered
DELIVERED 1610612752 0x60000010 REASON_DELIVERED + 0x10 Delivered and destination known on-net
DELIVERED 1610612753 0x60000011 REASON_DELIVERED + 0x11 Delivered to Virgin MVNO
REJECTED 268501248 0x10010100 REASON_REJECTED_BILLING_PREPAYUNSUP Rejected - prepay not supported
FAILED 1359151616 0x51030200 REASON_FAILED_DESTTEMP_SIMFULL + 0x01000000 Failed - SIM full, but post billing
(i.e. subscriber was billed - if on net)
BUFFERED 822083840 0x31000100 REASON_BUFFERED_BILLING_SUCCESSFUL + 0x01000000 Buffered - Message delivery state unknown as carrier does not support handset delivery reports, but message successfully billed

Variations between carriers

Not all carriers support the same level of detail, and not all delivery report reason codes are therefore available on all carriers. For instance, many US carriers do not support handset delivery reports, in which case, REASON_DELIVERED would never be returned. Tables showing which reason codes are available for each carrier are available here.

For more information, please contact us at 1-877-698-3532 or via email at sales@uk.openmarket.com.