Child pages
  • How to add new Error Code
Skip to end of metadata
Go to start of metadata


  1. In lens-errors.conf create a new entry under the section corresponding to the module in which you want to return the new Error Code.

  2. Make the corresponding entry in the Enum for error codes corresponding to that module. This ensures a more readable and less error prone way of using the errorCode unique id.

  3. Create a new instance of LensException using the Enum that you defined in step 2 and throw it where you want to return the new Error Code


See the explanation in the following section and Example  below for more details.


How it works?

On startup Lens Server initializes an instance of ErrorCollection  from ErrorCollectionFactory using ErrorCollectionFactory.createErrorCollection(

This process involves reading lens-errors.conf file and overriding it with lens-errors-override.conf (if any)  Each conf file follows the format of a typesafe config file  and roughly has a layout like below


Each entry in the file defines

  1. an errorCode - A unique numerical identifier to identify the error. This should be unique across all errors as ErrorCollections uses this value to get the corresponding instance of LensError.

  2. an httpStatusCode representing the status code which will be set on the Response in case of error.

  3. A string / template -  This can either be a plain string(e.g."Session id not provided. Please provide a session id.") or a string template (e.g. "XML invalid: %s")  to which arguments can be provided.
  4. payloadClass - class representing the payload. Lens will use reflection to get the Class for the corresponding string. In lens-errors.conf errors defined with different error codes must have different payloadClass. These are used to create JAXBContext to serialize and deserialize the responses.

Corresponding to each section in the lens-errors.conf we have enums defined for errors of that module e.g. LensCommonErrorCode for lens-api module and LensServerErrorCode for lens-server module. When developers want to throw an exception they use these enums to create an instance of  LensException


For an entry like below in the lens-errors.conf

we have defined following entry in the enum LensCubeErrorCode in lens-cube module


Here 3101 is the errorCode which is same as the errorCode defined in the lens-errors.conf entry. When throwing exception we use this to create an instance of LensException as below.

Here the second argument will be used to format the template provided in errorMsg in lens-errors.conf


Once the Exception is thrown Lens uses JAX-RS's  ExceptionMapper capability to convert exceptions to appropriate response. The Class LensExceptionMapper implements the ExceptionMapper interface and for a given exception it prepares the appropriate Response. It sets the Http Status code of the response using 

and it sets the response to 

as the entity. If any payloadClass is registered then it will be used by the JAXBContext  to serialize the response.


  • No labels