Error Detection and Error Communication
Error detection and communication happens at TSS and at the User Client. Both types of failures require
one side to communicate the failure to the other. They are both discussed within separate sections below.
TSS Error Detection
TSS 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 TSS:
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
{
"url": "<the url used by the POST>",
"error": "SeeTableBelowForPossibleValues",
"message": "The user does not have permissions." // for example
}
If the User 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 TSS to communicate the issue in printable text to aid debugging and integration. The User Client 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 User Client 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 TSS.
A maintenance window is in progress at TSS.
Permanent error examples:
An invalid ID or password was provided by the User Client.
The user does not have permissions to complete the action.
The TFN provided was not formatted correctly (e.g. “800pizza”).
The TFN (8000001212) was not in the voice DB therefore could not be enabled.
A field is missing in the JSON portion of the POST, such as the id, pwd, tfn, etc.
An unknown field is in the JSON portion of the POST.
The following table describes the possible error response HTTP status codes.