Sign up Login

USA - SMS - Delivery reports USA

Follow

Q: Which carriers support delivery reports in USA?

 

A: The carriers that supply delivery receipts are:

 

·         Verizon
·         T-Mobile
·         AT&T
·         Sprint - premium messages only - This carrier does not support messaging delivery receipts on their network. The delivery receipts returned are showing succesful or unsuccesful billing but not actual delivery on handset.
·         US Cellular
·         Alltel
Nextel, Boost, Cellular One, and Virgin do not support delivery receipts.

·         Verizon

·         T-Mobile

·         AT&T

·         Sprint - premium messages only - This carrier does not support messaging delivery receipts on their network. The delivery receipts 

          returned are showing succesful or unsuccesful billing but not actual delivery on handset.

·         US Cellular

·         Alltel

 

Nextel, Boost, Cellular One, and Virgin do not support delivery receipts.

 

This below guide describes reason codes, as available on the US Premium Short Message Service (PSMS) via 96527, and provides technical information to assist the client in its use. Note on some of our legacy codes reason codes are not available. The guide provides detailed descriptions of the reason codes, the carrier support of each code and guidelines on the real time logic which the client should implement within their application to handle the codes correctly. 

Mobile operators provide a large set reason codes describing billing transaction or message delivery failures. 

Premium Transaction Tracking simplifies the interpretation of diverse and changing carrier error codes, whilst retaining sufficient depth of real  time reporting to allow the client to implement meaningful and effective business logic. 

These reason codes are an aggregation of the similar actionable error codes returned by all carriers, they allow clients to implement real time logic in response to different types of errors. Examples of client business logic in response reason codes include: 

• Retry strategy for failed messages, ranging from "do not retry" to retry mechanisms with applicable schedules, to the failure reason 

• Send non-premium MT responses to subscribers who request services and cannot be billed for or provided such services 

• Removal/clean-up of subscriber phone number databases in the cases where failure is due to a permanently invalid destination number 

• Implementation of specific business rules that carriers may require. 

The support of reason codes may vary from carrier to carrier. Also, since reason codes are dependent on the information that txtNation receives from the carriers, not all reason codes are applicable to all carriers. 

 

Understanding Reason Codes

The status parameter provides a high level description of the delivery status of the transaction: 

 • acked: accepted by the carrier / successfully billed (only on some carriers)

 • delivered: delivered to the recipient's handset / successfully billed (only on some carriers)

 • buffered: queued in the SMSC. Status will always change.

 • failed / Non-delivered: message has not been delivered

 • unknown: the SMSC has failed to deliver notification about the delivery success 

These statuses will be accompanied by a reason code as described below. The following table provides a full list of the reason codes. Further below details the support of codes for each carrier and the recommended response logic which the client should implement. 

The table also includes an indication of whether each status is: 

• Intermediate – this is not the final status for this message and a subsequent status indication should be expected. No action needs to be taken for these indications.

• Permanent – this message is in the final state and the failure reason is permanent, i.e. if the message were submitted again the same failure would result

• Temporary – this message is in the final state but the failure reason is temporary, i.e. if the message were submitted again the same failure would not necessarily result

• Unknown – the reason for failure is not known. These are considered permanent failures. 

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Buffered 1 Phone related Intermediate Intermediate state notification that the message has not yet been delivered due to a phone related problem but is being retried.
Buffered 2 Deliverer related: message within carrier Intermediate Used to indicate that the message has not yet been delivered due to some carrier related problem but is being retried within the network.
Acked 3 Accepted by carrier Intermediate Used to indicate that the message has been accepted by the carrier. For certain carriers, this may be interpreted that the carrier has reported successful billing of the subscriber. 
Delivered 4 Delivered to mobile device Permanent The message was delivered.
Failed 5 Message failed

– detailed reason unknown

Unknown The message has been confirmed as undelivered but no detailed information related to the failure is known.
Unknown 6 Final status of message is unknown Unknown It cannot be determined whether this message has been delivered or has failed due to lack of final delivery state information from the carrier.
Buffered 7 Credit related – message may be being

retried

Intermediate The message has not yet been delivered due to insufficient subscriber credit but is being retried within the network.
Failed 8 Message expired within the carrier and failure reason is unknown Check

Carrier matrix

Used when a message expired (could not be delivered within the life time of the message) within the carrier SMSC but is not associated with a reason for failure.
Failed 20 Permanent carrier error Permanent Used when a message in its current form is undeliverable

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 21 Credit related: message has been retried by carrier Temporary Only occurs where the carrier accepts the message before performing the subscriber credit check. If there is insufficient credit then the carrier will retry the message until the subscriber tops up or the message expires. If the message expires and the last failure reason is related to

credit then this error code will be used.

Failed 22 Credit related: message has NOT been retried by carrier Temporary Only occurs where the carrier performs the subscriber credit check before accepting the message and rejects messages if there are insufficient funds available. 

For Virgin Mobile USA subscribers only, the client should respond with the following message "You do not have enough funds to participate in this program. Please visit www.virginmobileusa.com to top up your account."

Failed 23 Absent subscriber permanent Permanent Used when the message is undeliverable due to an incorrect / invalid / blacklisted / or permanently barred MSISDN

for this carrier. This MSISDN should be removed from the client's database and not be used again for message submissions to this carrier.

Failed 24 Absent subscriber temporary Temporary Used when the message is undeliverable due to an incorrect / invalid / blacklisted / or temporarily barred MSISDN for this carrier.

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 25 Carrier network failure Temporary Used when the message has failed due to a temporary condition in the carrier network. This could be related to the SS7 layer, SMSC or gateway.
Failed 26 Phone related error Temporary Used when a message has failed due to a temporary phone related error, e.g. SIM card full, SME busy, memory exceeded etc. This does not mean the phone is unable to receive this type of message/content (refer to error code 27).
Failed 27 Permanent phone related error Permanent Used when a handset is permanently incompatible or unable to receive this type of message (e.g. MMS compatibility).
Failed 29 Content related error Permanent Used when this specific content is not permitted on the network/short code.
Failed 30 Subscriber spend limit exceeded Temporary Used when message fails or is rejected because the subscriber has reached the predetermined spend limit for the current billing period.
Failed 31 Subscriber unable to be billed Temporary (Permanent on one carrier) Used when the MSISDN is for a valid subscriber on the carrier but the message fails or is rejected because the subscriber is unable to be billed, e.g. the subscriber account is suspended (either voluntarily or involuntarily), the subscriber is not enabled for bill- to-phone services, the subscriber is not eligible for bill-to-phone services, etc.
Failed 32 Subscriber Wallet not provisioned Permanent Subscribers are not eligible to be premium billed unless they have enrolled with the carrier for a Wallet. This error is returned if the subscriber has not set up a Wallet or is not a subscriber on the network.

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 33 Age verification failure Permanent End user failed age verification checks for the requested content.
Failed 37 Subscription related failure/Duplicat e request Permanent Used where the carrier platform supports subscription management and a message has failed because it has been submitted against a subscription which is invalid / closed. In the case of AT&T this code is returned if the request is a duplicate of an active purchase request that has not yet been confirmed by the end-user. The opt-in has been re-sent to the subscriber.
Failed 38 Invalid subscription operation Permanent Used where the carrier platform supports subscription management and an operation has failed because it is invalid e.g. it is not supported on the particular subscription.
Failed 40 Message delivered – billing failed Permanent Used in the rare occurrence of a message being delivered but the billing event failing due to a temporary problem within the operator network.
Failed 41  
Authorization

Failed

Permanent  
Carrier could not authorize payment for the transaction.
Failed 43 Message was rejected because the MSISDN is blacklisted Permanent MSISDN has been rejected because the carrier has blacklisted the number. Please REMOVE this number from database as it is a deactivated number and will not be billable. (implemented as part of carrier specific blacklisting programs)

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 48 Message was blocked because the content rating of the subscriber is lower than that of the PSMS application Permanent Used specifically for Verizon Content Filtering, and applicable to PSMS. The client must cancel the subscriber's subscription. No other action is required of client, since an automatic response to the subscriber with an informative free SMS MT is sent. 
Failed 49 Service Denied for this subscriber Permanent Either the carrier or the end user has blocked service to this number. Applicable to both SMS and MMS. Client must cancel all of the subscriptions for the subscriber. No other action is required of client, since an automatic response to the subscriber with an informative free SMS MT is sent.
Failed 50 Invalid WAP Push Permanent Used specifically for Verizon WAP Push messages. Returned when the WAP Push binary message could not be fully decoded because of one or more invalid elements.
Failed 51 Content could not be retrieved Temporary Used specifically for Verizon WAP Push messages. Returned when the client's server could not be accessed to retrieve the

content.

Failed 52 Content file not available Permanent Used specifically for Verizon WAP Push messages. Returned when the specific content file was not found on the client's server. Typically this occurs where the content format requested for the specific mobile device is not supported.

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 53 Message was blocked because the content rating of the subscriber is lower than that of the PSMS application Permanent The client must cancel the subscriber's subscription. No other action is required of client, since an automatic response to the subscriber with an informative free SMS MT is sent.
Failed 54 Indeterminate Age Verification Permanent This transaction requires the end user's age to be verified and the carrier could not perform that action.
Failed 55 Subscription failed because it was a duplicate subscription Permanent This code is returned after an attempt to set-up a duplicate subscription.
Failed 56 Duplicate purchase, opt- in re-sent Permanent The request is a duplicate of an active purchase request that has not yet been confirmed by the end-user. The opt-in has been re-sent to the subscriber. The client must not retry.
Buffered 59  
Message is delivered but not billed yet
Intermediate  
The message was delivered but has not been billed yet. The client should not try to re-send the purchase request.
Failed 70 Opt-In Expired Permanent This code is returned after an Opt-In request that was sent to the subscriber times out (12 hours). The client must not retry until the subscriber requests to Opt-In to the same campaign again.
Failed 71 Message failed because of missing

product description for billing literal

Permanent The message is missing a key piece of data. Clients should add this missing piece of data and then retry the message. The message will fail if it's simply retried as it is.

 

Status

Description

Reason Code

Reason

Description

Intermediate

/ Permanent/ Temporary

  •  Explanation
Failed 72 Message failed because of incorrect or invalid carrier configuration settings or because the carrier took administrative action to delete the message. Permanent The carrier are not ready to process the message due to some missing/invalid configuration settings in the carrier network. 

This is also used if the carrier took manual actions to remove the message from their system for any reason.

Failed 75 Refund denied Permanent Used where the carrier platform supports refunds on subscription cancellation and the refund request was denied.
Failed 78 Invalid subscription operation Temporary Used where the carrier platform supports subscription management and an operation has failed but can be retried.
Failed 82 Subscription failed due to internal error Temporary Subscription failed due to internal system error.
Failed 121 Insufficient Funds, Subscription failed to bill Permanent Used where carrier requires clients to remove the subscription requiring the end user to re-opt in when funds are available.

 

Carrier support of codes and recommended logic  The following tables indicate the carriers for which each code is supported and the recommended business logic which the client should implement. 

 

Reason Code and Description
  •  Recommended Client Business Logic (code not supported where shaded)
 US Cellular AT&T  T- Mobile Nextel

/ Boost

Alltel, Dobson Sprint
1 Phone related IS N/A N/A N/A N/A IS
2 Deliverer related: message within carrier IS N/A IS IS N/A IS
3 Accepted by carrier IS IS IS IS IS IS
4 Delivered to mobile device DNR DNR DNR N/A DNR DNR1
5 Message failed – detailed reason unknown DNR DNR DNR DNR DNR DNR
6 Final status of message is unknown DNR DNR DNR DNR DNR DNR
7 Credit related

– message may be being retried

N/A N/A N/A N/A N/A N/A
8 Message expired within the carrier and failure reason is unknown DNR Sched C (renewals)

, DNR

(all else)

Sched

C

N/A DNR N/A
20 Permanent carrier error DNR DNR DNR DNR DNR DNR
21 Credit related: message has been retried

by carrier

N/A N/A N/A N/A DNR N/A
22 Credit related: message has NOT been retried by carrier Sched B Sched B Sched

B

N/A Sched B N/A

 

1   Due to the fact that Sprint requires Content Aggregators to perform billing transaction based on successful messaging transaction, a Delivery Notification means that the message has been Confirmed by the Sprint SMSC AND a successful Billing Receipt has been received from the Sprint billing gateway.

Reason Code and Description
  •  Recommended Client Business Logic (code not supported where shaded)
 US Cellular AT&T  T- Mobile Nextel

/ Boost

Alltel, Dobson Sprint
23 Absent subscriber permanent DNR, RDB DNR, RDB DNR, RDB DNR, RDB DNR, RDB DNR, RDB
24 Absent subscriber temporary Sched

B

N/A Sched

B

N/A N/A N/A
25 Carrier

network failure

Sched

C

Sched A Sched

A

Sched

A

Sched

A

Sched A
26 Phone related error Sched

B

Sched

B

Sched

B

N/A Sched B Sched

B

27 Permanent phone related error N/A N/A DNR, RDB N/A N/A N/A
29 Content related error N/A DNR DNR N/A N/A DNR
30 Subscriber spend limit exceeded Sched

C

    Sched C, INF
Sched

C

Sched

C, INF

Sched

C, INF

N/A
31 Subscriber unable to be billed Sched

C

DNR, RDB DNR, RDB Sched

C, INF2

Sched

C, INF

    Sched C, INF
32 Subscriber Wallet not provisioned N/A N/A N/A DNR N/A N/A
33 Age verification failure N/A N/A N/A N/A N/A N/A
37 Subscription related failure/Duplica te request N/A DNR DNR N/A N/A N/A
38 Invalid subscription operation DNR DNR DNR N/A N/A N/A
40 Message delivered – billing failed N/A N/A N/A DNR N/A DNR3
41  Authorization

Failed

DNR DNR DNR N/A N/A N/A
43 Message was rejected because the MSISDN is blacklisted N/A N/A N/A DNR, RDB N/A DNR, RDB

 
 2   Nextel/Boost subscribers require a credit card to be registered with the carrier to access premium services. Messages which fail because the registered credit card is invalid will fail with this reason code.

3   Due to the fact that Sprint requires Content Aggregators to perform billing transaction based on successful messaging transaction, there is circumstances where the MT message has been Confirmed by Sprint's SMSC but subsequent Billing Request fails. Clients shall not retry even though it is temporary error.

 

Reason Code and Description
  •  Recommended Client Business Logic (code not supported where shaded)
 US Cellular AT&T  T- Mobile Nextel

/ Boost

Alltel, Dobson Sprint
48 Message was blocked because the content rating of the subscriber is lower than that of the PSMS application N/A N/A N/A N/A N/A N/A
49 Service

Denied for this subscriber

DNR, RDB DNR, RDB N/A N/A N/A N/A
50 Invalid WAP Push N/A N/A N/A N/A N/A N/A
51 Content could not be retrieved N/A N/A N/A N/A N/A N/A
52 Content file not available N/A N/A N/A N/A N/A N/A
53 Message was blocked because the content rating of the subscriber is lower than that of the PSMS application N/A N/A N/A N/A N/A N/A
54 Indeterminate Age Verification N/A N/A N/A N/A N/A N/A
55 Subscription failed because it was a duplicate subscription DNR DNR N/A N/A N/A N/A
56 Duplicate purchase, opt- in re-sent N/A DNR N/A N/A N/A N/A
59 Message is delivered but not billed yet IS N/A N/A N/A N/A N/A
70 Opt-In Expired DNR DNR N/A N/A N/A N/A
71 Message failed because of missing product

description for billing literal

DNR/ May Retry with full params DNR/ May Retry with full

params

N/A N/A DNR/ Retry with full params N/A

 

Reason Code and Description
  •  Recommended Client Business Logic (code not supported where shaded)
 US Cellular AT&T  T- Mobile Nextel

/ Boost

Alltel, Dobson Sprint
72 Message failed because of incorrect or invalid carrier configuration settings or because the carrier took administrative action to delete the message. DNR DNR DNR N/A N/A N/A
75 Refund Denied by carrier N/A DNR DNR N/A N/A N/A
78 Invalid subscription operation N/A N/A Retry on renew al date N/A N/A N/A
82 Subscription failed due to internal system error N/A N/A N/A N/A N/A N/A
121 

 

Insufficient

Funds

N/A N/A N/A N/A N/A N/A
Reason Code and

Description

Recommended Client Business Logic (code not supported where shaded)
Boost

Unlimited

Verizon

Wireless

Virgin
1 Phone related N/A IS N/A
2 Deliverer related: message within carrier IS N/A N/A
3 Accepted by carrier IS IS N/A
4 Delivered to mobile device DNR DNR N/A
5 Message failed – detailed reason unknown DNR DNR DNR
6 Final status of message is unknown DNR DNR DNR

 

Reason Code and Description Recommended Client Business Logic (code not supported where shaded)
Boost

Unlimited

Verizon

Wireless

Virgin
7 Credit related – message may be being retried N/A N/A N/A
8 Message expired within the carrier and failure reason is unknown N/A DNR N/A
20 Permanent carrier error DNR DNR DNR
21 Credit related: message has been retried by carrier N/A N/A N/A
22 Credit related: message has NOT been retried by carrier N/A N/A Sched B
23 Absent subscriber permanent DNR, RDB DNR, RDB DNR, RDB
24 Absent subscriber temporar y N/A Sched B N/A
25 Carrier network failure Sched A Sched A Sched A
26 Phone related error N/A Sched A N/A
27 Permanent phone related error N/A DNR4 N/A
29 Content related error N/A DNR N/A
30 Subscriber spend limit exceeded

 

    Sched C, INF
N/A N/A

 4   This code is returned when a WAP Push message is submitted to a Verizon mobile device which is incapable of receiving MMS messages.

Reason Code and Description Recommended Client Business Logic (code not supported where shaded)
Boost

Unlimited

Verizon

Wireless

Virgin
31 Subscriber unable to be billed Sched C, INF5 N/A N/A
32 Subscriber Wallet not provisioned N/A N/A N/A
33 Age verification failure N/A N/A N/A
37 Subscription related failure/Duplicate request N/A N/A N/A
38 Invalid subscripti on operation N/A DNR N/A
40 Message delivered

– billing failed

DNR N/A N/A
41  
Authorization Failed
N/A N/A N/A
43 Message was rejected because the MSISDN is blacklisted N/A DNR, RDB N/A
48 Message was blocked because the content rating of the subscriber is lower than that of the PSMS applicatio n N/A DNR N/A
49 Service Denied for this

subscriber

N/A DNR, RDB N/A
50 Invalid

WAP Push

N/A DNR N/A

 

5   Nextel/Boost subscribers require a credit card to be registered with the carrier to access premium services. Messages which fail because the registered credit card is invalid will fail with this reason code.

Reason Code and

Description

Recommended Client Business Logic (code not supported where shaded)
Boost

Unlimited

Verizon

Wireless

Virgin
51 Content could not be retrieved N/A Sched A N/A
52 Content file not available N/A DNR N/A
53 Message was blocked because the content rating of the subscriber is lower than that of the PSMS application N/A DNR N/A
54 Indeterminate Age Verification N/A N/A N/A
55 Subscription failed because it was a duplicate subscription N/A N/A N/A
56 Duplicate purchase, opt-in re- sent N/A N/A N/A
59 Message is delivered but not billed yet N/A N/A N/A
70 Opt-In

Expired

N/A N/A N/A
71 Message failed because of missing product description for billing literal N/A N/A N/A

 

Reason Code and Description Recommended Client Business Logic (code not supported where shaded)
Boost

Unlimited

Verizon

Wireless

Virgin
72 Message failed because of incorrect or invalid carrier configuration

settings or because the carrier took administrative

action to delete the message.

N/A N/A N/A
75 Refund Denied by carrier N/A N/A N/A
78 Invalid subscription operation N/A N/A N/A
82 Subscription failed due to internal system error N/A Sched A N/A
121 

 

Insufficient Funds N/A
    DNR, RSS
N/A

Carrier indication of successful billing 

A number of carriers do not provide full delivery receipt information and hence messages will not reach the final state "Delivered to the mobile device", as indicated by reason code 4. The following table specifies which reason code may be interpreted as reported billing success for each carrier. Note that this only applies to delivery notifications related to premium billed MT messages. 

 

Carrier
  •  Reason Indicating Billing Success
    Reason Description
    Reason Code
AT&T
    Delivered to mobile device
4
Verizon Wireless
    Delivered to mobile device
4
Sprint
    Delivered to mobile device
4
T-Mobile
    Delivered to mobile device
4
Nextel
    Accepted by carrier
3
Boost (All)
    Accepted by carrier
3
Dobson
    Accepted by carrier
3
Alltel
    Delivered to mobile device
4
Virgin Mobile
    Accepted by carrier
3
US Cellular
    Delivered to mobile device
4

 

Notes on retry/business logic 

The recommended business logic should be implemented as follows: 
 
 

• IS (Intermediate State) – this is not the final status for this message and a subsequent status indication should be expected. No action needs to be taken for these indications. 

• N/A ("Not Applicable") Clients should not see these codes on the specific carrier, therefore no action needs to be specified. 

• DNR (Do Not Retry) – the message submission has failed with a permanent failure reason. The message should not be resubmitted in its current form. 

• Schedule A (Immediate Retry) – The failed message can be retried immediately as there is high probability the message will be successfully delivered in this case. If the same message generates this error five times in a row, the client should attempt to retry on Schedule B. 

• Schedule B (Incremental Retry) – The message requires a change in the status of the subscriber (e.g. switching the phone on, topping up a pre-pay account) for the message to be delivered. A medium frequency retry schedule is appropriate to maximize chances of delivery, whilst not creating unnecessary traffic. It is suggested to retry the message after 5 minutes, 10 minutes and then every 30 minutes. If the situation persists after 24 hours, the client should attempt to retry on Schedule C. 

• Schedule C (Long Condition Retry) – The message has failed to be delivered for a reason which is unlikely to be resolved in a short time frame, although this is not necessarily a permanent reason for failure. The message may be resubmitted if it is still appropriate (i.e. the content and charge is still valid). It is suggested to retry once every 24 hours for up to 7 days. If the message is still failed after this, it should not be retried further and removed from the database. 

• RDB (Remove From Database) – The subscriber number used is invalid for submissions to this carrier. It should be removed from all database records held by the client to avoid further attempts to use it.  Any opt-out actions that a specific carrier may require (e.g. VZW OIOO, AT&T OPPC) should be performed for all impacted subscriptions. NOTE: if an opt-out action results in an error code that has RDB as a recommended action, do not take further action as this could lead to an infinite loop. 

• RSS (Remove Single Subscription) – This individual active subscription needs to be ended immediately It should be removed from all database records held by the client to avoid further attempts to use it. Any opt-out actions that a specific carrier may require (e.g. VZW OIOO, AT&T OPPC) should be performed for this individual subscription 

 

• INF (Information Message) – The client may choose to send a standard rate MT message to inform the subscriber that the requested service is not available. 

• NEXTEL (Nextel/Boost Specific Wallet Enrolment Message) – The client should send a standard rate MT message to the subscriber to advise them to register for a Wallet online on the carrier's website. The client should not attempt to retry the premium MT message unless the subscriber reinitiates the purchase request. Note that Nextel/Boost also returns this error code for subscribers who are unknown on their network. 

You must make your application configurable to allow the retry logic to be modified in future. The logic recommended in this guide may be updated to meet carrier requirements as they arise. 
 
 
 
 

Was this article helpful?
0 out of 0 found this helpful

Comments

  • Avatar
    Matthew Elvey

    Is this up to date? It's dated 2010.  I understand that more US carriers do not support delivery receipts any more.  Can you update it?

Powered by Zendesk