Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Structured Error Messages

Structured Error Messages

This document provides detailed information on how structured error messages are generated in Commerce Engine and made consumable by end users. For a general overview of structured messages are and how they are work, see Structured Messages in the Touchpoint Developer's Guide.

Structured error messages go through a number of transformations from their generation in Commerce Engine through to being presented to the user. A structured message goes through three transformations: one in Commerce Engine and two in Cortex. Separating the transformations allows for the separation of data between Commerce Engine, Cortex and the client browser.

In general, structured error messages are generated through the creation of constraint violations and invalid business states in Commerce Engine. These violations are then transformed into a set of com.elasticpath.common.dto.StructuredErrorMessage objects. Commerce Engine then generates an exception which returns both an exception message and the set of StructureErrorMessage objects and passes these to Cortex.

In Cortex, the set of StructuredErrorMessage objects are then extracted from the exception and passed into another transformer, which then transforms the objects into objects. This transformation replaces the Commerce Engine field names with front-end field names understandable by the client. To see which error message codes map to which responses, see the API Reference.

After the second transformation, the resulting structure is attached to an execution result. The execution result moves up and is converted to an operation result. The final transformation is from Message to com.elasticpath.schema.StructuredMessage occurs in this stage. StructuredMessage enriches the standard JSON response of Message, providing additional information and fields, such as the linked-to and blocks fields.

Structured Message Origins

How a structured error message moves from Commerce Engine to Cortex varies based on the message's origins as either a constraint violation or an invalid business state.

Structured Messages as a Result of a Constraint Violation

One way structured messages are created is as a constraint violation in Commerce Engine. Cortex uses two validators for validation: the Apache BVal and implementation of the JSR-303 framework, and the Hibernate Validator implementation of the JSR-349 framework.

In Commerce Engine, validation is performed before any CUD (Create, Update, Delete) operation is executed. This maintains the integrity of the database and prevents the execution of errors coming from the operation. If validation fails, the output is a set of constraint violations. This set of constraint violations goes through a constraint violation transformer. In the transformer, information extracted and then converted it into a list of structured error messages. The resulting data is then wrapped inside a validation exception, and moves into Cortex for conversion.

See Field Validation Errors for a list of messages returned by Cortex.

Structured Messages as a Result of an Invalid Business State

Another way structured messages are created is as a result of an invalid business state. In this scenario, a structured error message is constructed manually, eliminating the need for a transformer.

Like constraint violation errors, invalid business state errors are returned with an invalid business state exception to move into Cortex for conversion.

See Business State Errors for a list ot messages returned by Cortex.