Error Detection
This document assumes that if the syntax of the HTTPS GET or POST is, itself, invalid, then the typical web server failures (e.g. HTTPS 404) occur; those failures are addressed outside of this specification. Once the HTTPS header is validated and the JSON syntax is parsed successfully, then the next level of error detection occurs.
The RouteLink® Server uses an error field in the response to a request to communicate a parameter or JSON content failure. It also uses this response to communicate its inability to complete the request for any other reason. A message field is supplied to provide more information in free-form, printable, text (to aid client side debugging). The following is an example JSON response indicating that an error was encountered by the RouteLink Server:
{
"error": "SeeTableBelowForPossibleValues",
"message": "Explanatory text is included here."
}
The following table describes the possible values for the error field.
| Error Field Values | ||
| Error Value | Comments | Action |
| "temporary" | A temporary error on the server has occurred. The HTTPS connection has been successful to this point, but the server is unable to complete the request at this time. Sending the same request again, but at a later time, is expected to be successful. An example could be a temporary database outage during maintenance. | The RouteLink Client SHOULD retry the request later, waiting at least 60 seconds before retrying. |
| "permanent" | A permanent error has occurred that MUST be addressed by the client. Resending the request will NOT yield success, so retrying is not reasonable without some additional action being taken first. An example is an invalid field in a request. |
The RouteLink Client MUST stop sending the request and inspect the message field to learn more about the problem. Contacting Somos support at routelinkhelp@somos.com may be required based on the issue. Once the problem has been addressed, the RouteLink Client can resume communication. |
If the RouteLink Client 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 server to communicate the issue in printable text to aid RouteLink Client debugging. The RouteLink Client MUST NOT depend upon any values in the message text, since the text is subject to change at the discretion of the server at any time without notice. Up to 1000 printable characters (including whitespace such as carriage returns, etc.) are allowed for flexibility.
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 RouteLink Server 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 RouteLink Server.
A maintenance window is in progress at the RouteLink Server.
Permanent error examples:
A field is missing in the request.
An unknown field is present in the request.