VersaCloud's Error Codes
In order to make it easier for developers to use VersaCloud, we designed it from the very beginning to be as detailed as possible when reporting errors. All APIs are defined to have a return value of a single type plus a predefined set of error codes.
However, having APIs returning values from two different sets (the 'normal' return values and the error codes) determines the need to define a mechanism to clearly identify error codes as such. That is why on our cloud-based time-limited transaction manager all error codes have been defined as sixteen-character strings, which always start with the prefix ':@Err#', hence leaving effectively ten characters for the identification of the error. We chose the ':@Err#' prefix arbitrarily, just to avoid clashing error codes with normal strings.
Errorcodes have been defined as a type of our type system, and the complete list of errorcodes contains almost one thousand different error codes, fulfilling the promise to deliver detailed error information to developers. The part of the errorcodes following the ':@Err#' prefix is composed of three letters (identifying the problem area) and a seven decimal numeric code. Problem areas currently defined are 'Api' (errors related to API calls), 'Bal' (errors related to user balance), 'Cbk' (related to callbacks), 'Doc' (related to documentation), 'Err' (related to errors), 'Grp' (related to user groups), 'Lng' (related to languages), 'Met' (related to methods), 'Prm' (related to parameters), 'Qry' (related to queries), 'Rgt' (related to rights), 'Sol' (related to solutions), 'Tim' (related to time), 'Typ' (related to type), 'Usr' (related to users) and 'Vld' (related to valid values).
For example, error code ':@Err#Usr0000024' is returned when the user calling a method does not own the needed rights. Localized, complete descriptions of each error code can be obtained by calling the 'ErrorDocumentationGet' API (which returns ':@Err#Prm0200201' in case its second parameter is not recognized as an error code).
When defining new methods and solutions, developers can define their own custom error codes to be returned from back-end servers to front-end software through our transaction manager: the 'MethodErrorAddAllow' and 'MethodErrorAddCommit' APIs must be called to add new error codes, which can then be documented in various human languages by calling the 'ErrorDocumentationSetAllow' and 'ErrorDocumentationSetCommit' APIs.
Error codes usage can also be limited in time by calling the 'MethodErrorUntilSetAllow' and 'MethodErrorUntilSetCommit' APIs (custom error codes are always usable 'since' their creation, as they have to be used by developers during software tests; that is the reason why the corresponding 'MethodErrorSinceSet…' APIs do not exist). The 'MethodErrorSinceGet' and 'MethodErrorUntilGet' API calls can be used to retrieve the current limits of the time period the error code is Valid to be returned by a solution method. The 'MethodErrorValid' API call can be used to check if a specific error code is currently valid as a return value for a specific method.
US Patent Requested