This document will detail the working of the TextPower failure reporting process. The TextPower failure reporting process records the following types of information:
- Structural errors in API submissions to the TextPower APIs. This does not include errors in credentials submitted to TextPower! Since failure reporting, as with all other functions, must be restricted to known users, it is not possible to record credentialing errors.
- Errors which, while structurally correct, prevent a send from being made. These are the errors returned with a Not Sent prefix in the status field of send submissions. Errors are recorded separately for the 4 basic send types provided:
- Direct Sends o Queued Sends o Bulk Sends o Deferred Sends
- Errors which prevent an otherwise correct message submission from being delivered. These delivery errors are never retuned in the response packet to a submission but are reported later when the various carriers determine that the message cannot be delivered. There are a large number of these reasons ranging from a powered off phone to suspension of service for various reasons.
Errors can be reported in one of 3 ways:
- In the return packet of an API submission: This is existing method and is unchanged by the enhanced failure reporting process detailed in this document. Note that delivery errors cannot be reported in response packets because the error is not known at that time.
- From a page on the TextPower customer portal at https://customer.textpower.com
- Reported to a customer provided URL via a standard HTTP POST.
Error Data is divided into Primary Data and Delivery Data. Primary Data is any error that occurs in real time with a send. Delivery Data, also called Secondary Data arrives after a send has been complete. The time varies from a minimum of a few seconds to as long as 24 hours.
The Error Code is an integer that has a flag for each error type. The flag bits and their numerical equivalent are listed below;
Request = 1 ‘Errors which occur on an API submission Not Sent Direct = 2 ‘Errors that prevent a direct send from occurring
Not Sent Bulk = 4 ‘Errors that prevent a individual send in a bulk send
Post Out Errors = 8
Voice Submission = 16 ‘Error on a voice send
Carrier Submission Direct = 32 ‘Immediate errors returned by carrier
Carrier Submission Redirect = 64 ‘on a submission for the five
Carrier Submission Queued = 128 ‘send types
Carrier Submission Bulk = 256 Carrier Deferred = 512 ‘End of carrier immediate errors
Carrier = 2048 ’Delivery errors returned by carriers
Other = 32768 ‘Errors that do not fit into an specific category
Note: For Delivery Errors, a snippet of the contents of the message will be displayed in the PrimaryError area of both the posted XML and the portal web page. Normally for this type of error, the PrimaryError area is blank anyway. This is provided to assist you in determining which message is responsible for the delivery error. In cases where the PrimaryError has data already in it, the message snippet is appended to that data.
Failure Display Methods
Failure data accumulated by the system can be seen on the TextPower customer portal at https://customer.TextPower.com . Select the Failure Data sub-tab under the Message Data tab on the menu. Failure Data is kept for one month before erasure.
POST to Customer Server
You may also elect to have any failure data POSTed to your customer server. To get this data, you must request it from TextPower and supply the URL of your server to which you wish the data to be delivered. Data is POSTed out in XML form every 2 minutes. Since more than one error may have occurred in that period, more than one error may have occurred in that span. The XML is delivered in the POST variable FDXML. The XML format is:
<FailEntry ID="10025" Keyword="BigAl" FailCode="1" Numbers="8185551234" SendID="0" PrimaryFailDate="8/4/2013 1:23:01 PM" PrimaryError="Deferred Send requested but the time value supplied is not this year or next year.;Both Queued and Deferred Send Requested. Ambiguous.;" SecondaryFailDate="" SecondaryError="" />
<FailEntry ID="10026" Keyword="BigAl" FailCode="2" Numbers="8185554321"
SendID="0" PrimaryFailDate="8/5/2013 1:24:34 PM" PrimaryError="Not Sent:No
OptIn" SecondaryFailDate="" SecondaryError="" />