Class ExceptionDocumentation


public class ExceptionDocumentation extends Object
Table of content The exception hierarchy documentation.


The SDK makes use of exceptions from the Java JDK, such as IllegalArgumentException, and provides own exceptions which all inherit from BaseException.

Problems concerning the ApiHttpClient throw a ApiHttpException.

JSON serializing and deserializing problems throw JsonException.

ApiHttpException is a base exception for all error responses from Composable Commerce (HTTP status code >= 400).

ApiClientException expresses errors which can be recovered by the client side (HTTP status code >= 400 and < 500). ApiServerException is for server errors.

Exception hierarchy


If a command cannot be performed due to unfulfilled preconditions the API can return one error response with multiple errors (listing of error codes). The SDK will then put a BadRequestException into a CompletionStage.

Custom HttpExceptionFactory

In case a response with a status code of 400 or higher are treated as errors and raise exceptions. These exceptions are created by the DefaultHttpExceptionFactory. In case you want to override the handling you have to implement this interface and override the default methods if necessary.

import static org.assertj.core.api.Assertions.assertThatExceptionOfType;

import com.commercetools.api.client.ProjectApiRoot;

import com.commercetools.api.defaultconfig.ApiRootBuilder;

import com.commercetools.api.defaultconfig.ServiceRegion;

import io.vrap.rmf.base.client.*;

import io.vrap.rmf.base.client.error.HttpExceptionFactory;

import org.junit.jupiter.api.Test;
public class HttpExceptionFactoryTest {

    static class CustomExceptionFactory implements HttpExceptionFactory {
        public ApiHttpException create(ApiHttpRequest request, ApiHttpResponse<byte[]> response) {
            return new ApiHttpException(response.getStatusCode(), request.getSecuredBody(), response.getHeaders(),
                "something bad happened", response, request);

        public ResponseSerializer getResponseSerializer() {
            return ResponseSerializer.of();

    public void customFactory() {

        ProjectApiRoot client = ApiRootBuilder.of()

        assertThatExceptionOfType(ApiHttpException.class).isThrownBy(() -> client.get().executeBlocking())
                .withMessageStartingWith("detailMessage: something bad happened");


See the test code.

  • Constructor Details

    • ExceptionDocumentation

      public ExceptionDocumentation()