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.

Invalid Business State Errors

Invalid Business State Errors

An invalid business state error is an error thrown during a state change operation where a business condition is not fulfilled. Invalid business state error types prevent a state change operation from happening. Often the client can solve the underlying business error and then retry the state change operation successfully.

For example, when purchasing an order, the following scenarios could generate invalid business state errors:

  • An item in the cart isn't available in the requested quantity.
  • The shopping cart is empty.
  • A shipping address is missing.

Invalid business state error is mapped to the HTTP status code 409, which indicates the presence of a conflict. To help the client localize error messages and recover from this error type, the body of the HTTP response contains structured error messages.

Constructing Invalid Business State Errors

Unlike validation errors, which are generated during validation, invalid business state errors must be constructed manually.

To construct an invalid business state error:

  • Create a class which extends the InvalidBusinessStateException interface.

InvalidBusinessStateException objects return a collection of StructuredErrorMessage objects indicating why the failure state occurred. Optionally, the StructuredErrorMessage object can contain a StructuredErrorResolution object, which contains a link which can help the user resolve the error.

For example, AvalabilityException is a fully constructed invalid business state error:

  public class AvailabilityException extends EpSystemException implements InvalidBusinessStateException {
      private final List<StructuredErrorMessage> structuredErrorMessages;
      public AvailabilityException(final String message, final Collection<StructuredErrorMessage> structuredErrorMessages) {
          this.structuredErrorMessages = structuredErrorMessages == null ? emptyList() : ImmutableList.copyOf(structuredErrorMessages);
      public List<StructuredErrorMessage< getStructuredErrorMessages() {
          return structuredErrorMessages;
      public String getExceptionMessage() {
          return getMessage();