User Client Error Detection and the Error POST
The User Client may also encounter errors in the TSS responses. These types of errors are permanent
errors since the User Client is the client and TSS can never “retry” a response. Therefore, there is no
“temporary” concept of error in this direction.
The User Client communicates an error to TSS through a POST to a specific error URL: “/tss-user-apierror”.
The following is an example POST to indicate an error encountered by the User Client:
POST /api/v2/tss-user-api-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 TSS 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": "Acknowledging the error POST." // for example
}
The message field follows the same rules as described earlier.
The TSS SHOULD inform its operations personnel of the error encountered by the specific User Client
when the error POST occurs. Since this is a permanent error, it is expected that TSS and User Client
personnel would work together to resolve the issue. There is no expected automatic recovery for these
errors.
The following are some examples of potential User Client 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:
A TFN was invalidly formatted (e.g. too few chars) in a response.
A required field is missing in the JSON portion of the response.
Since there are no temporary failures encountered in this case, the User Client MUST ONLY issue error
POSTs that can be fixed by the TSS. In other words the User Client MUST NOT issue errors for issues
that it controls and TSS can do nothing about. Examples of issues that MUST NOT become errors in this
case are:
A database outage has occurred at the User Client.
A maintenance window is in progress at the User Client.
Instead, the User Client should refrain from sending any POST until the User Client is back in service.
The following table describes the possible response HTTP status codes.