SMS Gateway
HTTP Interface
Delivery Report Reason Codes
Overview
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
- Detailed reason codes
- Reason byte tables
- Examples
- Variations between carriers
Types of delivery report
The following delivery report types may be returned by the SMS Gateway:
| Type | Description |
|---|---|
| REJECTED | If 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. |
| BUFFERED | Buffered 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). |
| FAILED | Failed means that the message has been failed after it was submitted to the carrier for delivery. |
| DELIVERED | Delivered 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 |
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 |
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 |
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 |
Prepay billing unsupported | Fail | Billing of prepay subscribers is not supported on this carrier. | |
| 0x1.0102.. | REASON |
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 |
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 |
No carrier-controlled opt-in confirmation received | Fail | On carriers where the carrier controls an opt-in process (eg, AT&T USA OPPC), this reason code is returned if no positive opt-in is received within the timelimit allowed by the carrier. | |
| 0x1.0112.. | REASON |
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 |
Charge exceeds terms of subscription billing mandate | Fail | This charge exceeds the terms (eg, monthly limit) of a subscription billing mandate. | |
| 0x1.0114.. | REASON |
Previous opt-in process still active | Fail | On carriers where the carrier controls an opt-in process (eg, AT&T USA OPPC), this reason code is returned if there is already a pending opt-in process for this subscription. | |
| 0x1.012... | Reason code group: credit control | Billing | Group of billing-related errors: subscriber has reached a credit/spending limit. | ||
| 0x1.0120.. | REASON |
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 |
Subscriber has reached spending limit | Billing | Subscriber has reached a spending limit (eg, monthly spend cap). | |
| 0x1.0122.. | REASON |
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 |
Account closed | Fail | Attempt to bill against a closed account. This subscriber should not be billed further. | |
| 0x1.0132.. | REASON |
Account locked | Fail | Attempt to bill against a locked/suspended account. | |
| 0x1.0133.. | REASON |
Billing barred (reseller settings) | Fail | Subscriber obtains connectivity via a reseller; billing of this subscriber is therefore barred. | |
| 0x1.0134.. | REASON |
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 |
Invalid source address | Fail | Originator on this message was invalid. | |
| 0x1.0201.. | REASON |
Provisioning error | General | Shortcode has not been provisioned. Contact MX Telecom support. | |
| 0x1.0202.. | REASON |
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 |
Invalid destination | Fail | Temporary delivery problem to the destination. | |
| 0x1.0301.. | REASON |
Barred | Fail | Temporary bar on delivery of this content to the destination. | |
| 0x1.0302.. | REASON |
SIM full | Fail | Message could not be delivered as handset message memory is full. | |
| 0x1.0303.. | REASON |
Subscriber absent | Fail | Message could not be delivered as handset is absent from the carrier. | |
| 0x1.0304.. | REASON |
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 |
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 |
Barred | Fail | Delivery to this subscriber has been barred. | |
| 0x1.0402.. | REASON |
All SMS barred | Fail | This subscriber cannot receive bulk or premium SMS messages from any sender | |
| 0x1.0405.. | REASON |
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 |
Ported off-net | Fail | This subscriber is known to have ported off-net; delivery through this carrier is no longer possible. | |
| 0x1.0407.. | REASON |
Delivery barred (reseller settings) | Fail | Subscriber obtains connectivity via a reseller; messaging to this subscriber is therefore barred. | |
| 0x1.0408.. | REASON |
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 |
System error | General | Some part of MX Telecom or carrier systems not functioning correctly. Contact MX Telecom support for more details. | |
| 0x1.0501.. | REASON |
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 |
Bad message | Fail | Carrier rejected message contents. Used where we have no further information as to the problem with the contents. | |
| 0x1.0601.. | REASON |
Unicode not supported | Fail | Unicode (UCS2) messages are not supported on this carrier/shortcode. | |
| 0x1.0602.. | REASON |
Binary not supported | Fail | Binary (8-bit) messages are not supported on this carrier/shortcode. | |
| 0x1.0603.. | REASON |
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 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 |
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 whilst awaiting a billing action | ||
| 0x3.0103.. | REASON |
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 |
Invalid destination | Temporary delivery problem to the destination. | |
| 0x3.0302.. | REASON |
SIM full | Message could not be delivered as handset message memory is full. | |
| 0x3.0303.. | REASON |
Subscriber absent | Message could not be delivered as handset is absent from the carrier. | |
| 0x3.0304.. | REASON |
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 |
Message delivered to subscriber | Message delivered to handset. | |
| 0x620000.. | REASON |
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 |
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 | 1610612752 | 0x60000010 | REASON_ |
Delivered and destination known on-net |
| DELIVERED | 1610612753 | 0x60000011 | REASON_ |
Delivered to Virgin MVNO |
| REJECTED | 268501248 | 0x10010100 | REASON_ |
Rejected - prepay not supported |
| FAILED | 1359151616 | 0x51030200 | REASON_ |
Failed - SIM full, but post billing (i.e. subscriber was billed - if on net) |
| BUFFERED | 822083840 | 0x31000100 | REASON_ |
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.
