Error Detection and Error Communication
This specification assumes that if the syntax of the HTTP POST is, itself, invalid, then the typical web server REST failures (e.g. HTTP 404) occur; those failures are addressed outside of this specification. However, if the HTTP header is valid and the JSON syntax can be parsed, then the next level of error detection occurs.
Error detection and communication happens at the TSSRegistry™ and at the TFT Router. Both types of failures require one side to communicate the failure to the other. They are both discussed within separate sections below.
TSSRegistry Error Detection
The TSSRegistry uses an error field in the response to a POST to communicate a JSON content failure or its inability to complete the request for some other reason. A message field is also supplied to provide more information in free-form, printable, text (to aid debugging). The following is an example response to a POST indicating an error was encountered by the TSSRegistry:
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:36:00 GMT
Connection: close
{
"error": "SeeTableBelowForPossibleValues",
"message": "Explanatory text is included here."
}
The following table describes the possible values for the error field.
Disclaimer: Any images in this article are intended to be used as a guide for educational purposes only and they may differ slightly from the Production Environment.
If the TFT Router receives a response with an error value from the table above, it MUST take the action described in the table above.
The message field is free-form text, where the contents are otherwise not constrained by this specification. It allows the TSSRegistry to communicate the issue in printable text to aid debugging and integration. The TFT Router MUST NOT depend upon any values in the message text, since the text is subject to change completely at the discretion of the sender at any time without notice. Up to 1,000 printable characters (including whitespace such as carriage returns, etc.) are allowed for flexibility. The sender of a message field is encouraged to provide verbose information, as reasonable, to aid the debugging effort which could occur minutes, hours, or days later in a production environment.
It is unnecessary (and would likely be incomplete) to try to enumerate all the possible errors; however, they all fall into one of the categories in the table above (“temporary” or “permanent”) and are driven by the action the TFT Router must take. Below are some examples of errors to aid development. The text in these examples is NOT required in the message field -- it is only for explanatory purposes in this document.
Temporary error examples:
A database outage has occurred at the TSSRegistry.
A maintenance window is in progress at the TSSRegistry.
Permanent error examples:
An invalid ID was provided by the TFT Router.
An invalid password was provided by the TFT Router.
The ack value provided by the TFT Router is outside of the event sequence window.
The max value provided by the TFT Router is not in the allowed range.
A field is missing in the JSON portion of the POST, such as the id, pwd, ack, or max.
An unknown field is in the JSON portion of the POST.