Error Handling

Good APIs should properly report errors when error occurs. There are many scenarios that might cause error to occur. Wrong configuration setting, failed connection to a 3rd party API and invalid input are a few examples. There are two types of errors in AlchemyJ. They are System error and Model error.

Getting a list of system errors

System errors are errors raised by AlchemyJ Extended Functions such as ajExecuteSql, ajAuthenLdap, and ajCallWsRest. When an error occurs in an AlchemyJ Extended Function, it creates an error record in the System Error List. You can use ajGetSystemError to retrieve and search for errors on the System Error List.

Take ajAuthenLdap as an example, it will raise an error if the server name is an invalid LDAP server name. You can use =ajGetSystemError() to retrieve the error list.

ajGetSystemError([Cell_reference], [Function_name], [Error_message])

In this example, we leave all the parameters as blank so that it retrieves all errors on the System Error List. ajGetSystemError returns a list of records with 3 columns. Therefore, it should be entered as an array formula by selecting a 3-column range, type in the formula, and hit CTRL+SHIFT+ENTER.

Raising and getting a list of model errors

Besides system errors, there may be times when you want to manually handle an error. For example, when you catch a bad input or override a system error.

In this example, we use ajAuthenLdap to validate a user name and password against an LDAP server. ajAuthenLdap will return FALSE if the username and password do not match. We want to return a specific error message when this happens. This can be achieved by using ajRaiseError.

ajRaiseError(Error_message, [Error_code], [Cell_reference], [Run_condition],[Run_by_function_point_only])

In this example, we use "Invalid User Name or Password" as the error message, "100001" as the error code and ajGetAddress(C8) as the reference address.

After the error is raised by ajRaiseError, it can be retrieved by using ajGetModelError.

ajGetModelError([Cell_reference], [Error_code], [Error_message])

In this example, we specify the error code as "100001" so that only errors with error code "100001" will be returned. ajGetModelError returns a list of records with 3 columns. Therefore, it should be entered as an array formula by selecting a 3-column range, type in the formula and hit CTRL+SHIFT+ENTER.

Retrieving errors returned from an AlchemyJ REST API

AlchemyJ returns status code 502 when an error exists in the System Error List and Model Error List. The error content will be shown under the messages node.

Retrieving errors returned from an AlchemyJ Java method

try{
      String telephoneNum = biz.queryUserTelephone();
   }catch(AlchemyjFormulaExecutionException ajEx) {
      // Write your logic to handle the exception above
   }catch(Exception e){
      // Handle other exception
   }

Configuring REST API error handling behavior

The following properties in REST API worksheet can control how a REST API behaves when errors occur:

• alchemyj.stopOnFormulaError
• alchemyj.stopOnUserRaiseError
• alchemyj.throwOnFormulaError
• alchemyj.throwOnUserRaiseError

Refer to the REST API Worksheet for more details.