TFT Router Error Detection and Error Post
The TFT Router may also encounter errors in the TSSRegistry™ responses. These types of errors are permanent errors since the TFT Router is the client and the TSSRegistry can never “retry” a response. Therefore, there is no “temporary” concept of error in this direction.
The TFT Router communicates an error to the TSS through a POST to a specific error URL: “/tft-download-error”. The following is an example POST to indicate an error encountered by the TFT Router:
POST /tft-download-error HTTP/1.0
Content-Type: application/json
Content-Length: <num>
{
"id":"user",
"pwd":"password",
"error":"permanent", // “permanent” is the only allowed value here
"message": "Explanatory text is included here."
}
The message field follows the same rules as described earlier in this section. The TSSRegistry treats the error POST as a permanent error and issues this response as a way of acknowledging the error POST:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/plain;charset=ISO-8859-1
Content-Length: <num>
Date: Tue, 13 Jan 2015 16:37:00 GMT
Connection: close
{
"error": "permanent",
"message": "Explanatory text is included here."
}
The message field follows the same rules as described earlier, and in this example, it may be as simple as “The TFT Router sent an error POST.” Or, the TSSRegistry can choose to echo back the error message in the POST. In other words, this specification does not have any specific requirement for the contents of the message field -- it is up to the TSSRegistry.
The TSSRegistry SHOULD inform its operations personnel of the error encountered by the specific TFT Router when the error POST occurs. Since this is a permanent error, it is expected that TSSRegistry and TFT Router personnel would work together to resolve the issue and then when satisfied, the TFT Router can resume sending the download POST. The point: there is no expected automatic recovery for these errors.
The following are some examples of potential TFT Router encountered errors. This list is not expected to be complete, nor is the text in these examples required in the message field -- it is only for explanatory purposes in this document:
An invalid event command was provided by the TSSRegistry.
A sequence number gap was encountered in the event array.
A TFN was invalidly formatted (e.g. too few chars) in an event.
The number of events was more than the max value requested in the POST.
A field is missing in the JSON portion of the response, such as the “remaining” field.
An unknown field is in the JSON portion of the response.
Since there are no temporary failures encountered in this case, the TFT Router MUST ONLY issue error POSTs that can be fixed by the TSSRegistry. In other words the TFT Router MUST NOT issue errors for issues that it controls and the TSSRegistry can do nothing about. Examples of issues that MUST NOT become errors in this case are:
A database outage has occurred at the TFT Router.
A maintenance window is in progress at the TFT Router.
Instead, the TFT Router should choose to not send a download POST until it is back in service.