Package sys.exceptions

sys.exceptions

This package contains methods to work with exceptions.

getCode(exception)

Returns the error code in case the parameter passed is of type sys.exceptions.ScriptException. Otherwise return null.

The advantage of using this method instead of just calling sys.exceptions.ScriptException.code() is that you don’t need to worry if it is a platform exception or any other kind of exceptions. Otherwise you should first check it is a platform exception before fetching the code.

Parameters

Returns

string - The code of the exception or null.

Samples

// logs the code of a platform exception

try {
  var query = sys.data.createQuery('entityThatDoesNotExist');
} catch (e) {
  log('error code: '+sys.exceptions.getCode(e));
}

// when it is a Javascript exception it will return 'null'

try {
  // this var doesn't exist an will throw a Javascript error
  var a = doesNotExist * 5;
} catch (e) {
  log('error code: '+sys.exceptions.getCode(e));
}

getMessage(exception)

Returns the error message in the exception. If the parameter is a string, returns it. If it is a sys.exceptions.ScriptException, then returns the message contained inside. If it is an object, returns its JSON representation. Otherwise tries to cast the parameter to a string.

The advantage of using this method instead of just calling sys.exceptions.ScriptException.message() is that you don’t need to worry if it is a platform exception or any other kind of exceptions. Otherwise you should first check it is a platform exception before fetching the message.

Parameters

Returns

string or object - The message of the exception, a JSON object or just the string representation.

Samples

// logs the message of a platform exception

try {
  var query = sys.data.createQuery('entityThatDoesNotExist');
} catch (e) {
  log('error message: '+sys.exceptions.getMessage(e));
}

// logs the message of a Javascript exception

try {
  // this var doesn't exist an will throw a Javascript error
  var a = doesNotExist * 5;
} catch (e) {
  log('error message: '+sys.exceptions.getMessage(e));
}

getAdditionalInfo(exception)

Returns an object with additional info of the error if available. Keep in mind that this is not available in all exceptions but just a few. For example some endpoint exceptions could add information about the request that failed.

Parameters

Returns

string or object - An object with the additional info; will be an empty object if there is no additonal info.

Samples

// logs the message of a platform exception

try {
  app.endpoints.http.post(params);
} catch (e) {
  log('error additional info: '+sys.exceptions.getAdditionalInfo(e));
}

throwException(code, message)

Throws an exception with the given code and message. The main reason to use this method instead of using the Javascript throw keyword is that if this exception is caught and logged, you will be able to see the stack trace. Using the regular throw keyword does not provide the stack trace if you need to log the exception.

So always prefer this method instead of using the throw keyword.

Parameters

Exceptions

``

Samples

// throws an exception if the state is not 'new'

if (record.field('state').val() != 'new') {
  sys.exceptions.throwException('invalidState', 'Task must be in state new');
}

sys.exceptions.ScriptException

When there is an error in the platform or known errors in the scripts (like validation scripts), objects of this type will be thrown, containing an error code and a message.

code()

Returns the error code. Valid error codes are:

• validationErrors
• badRequest
• forbidden
• optimisticLocking
• timeout
• systemException
• unknownError

Returns

string - The error code

Samples

// logs the code of a platform exception

try {
  var query = sys.data.createQuery('entityThatDoesNotExist');
} catch (e) {
  log('error code: '+e.code());
}

message()

Returns the error message.

Returns

string - The error message

Samples

// logs the message of a platform exception

try {
  var query = sys.data.createQuery('entityThatDoesNotExist');
} catch (e) {
  log('error message: '+e.message());
}

throw()

Throws an exception using the method throwException(), where code and message are the values in this object.

Samples

// creates an exception and throw it

if (record.field('state').val() != 'new') {
  var exception = new sys.exceptions.ScriptException('invalidState', 'Task must be in state new');
  exception.throw();
}