Java SDK Middlewares


The ErrorMiddleware is used to react to erroneous HTTP responses. It will always be placed as the first middleware in the HandlerStack. The default implementation converts responses with a status code 400 or higher to exceptions. For creating the exceptions it uses an HttpExceptionFactory.

return next
.thenApply(response -> {
if (response.getStatusCode() >= 400) {
throw exceptionFactory.create(request, response);
return response;
Clipboard icon


The OAuthMiddleware is used to authenticate a request against the Composable Commerce APIs. The default implementation adds an auth header to the request instance. In case of an expired token, it will try to reauthenticate automatically. To retrieve an AuthenticationToken the OAuthHandler is called.

return failsafeExecutor.getStageAsync(() -> {
if (request.getHeaders().getFirst(ApiHttpHeaders.AUTHORIZATION) != null) {
return next.apply(request);
AuthenticationToken token = authHandler.getToken();
return next.apply(
Clipboard icon


The RetryRequestMiddleware configures a client to handle failures like gateway timeouts and version conflicts through retrying the request.

For retrying, an exponential backoff strategy is used which increases the wait time before each retry to avoid overwhelming the API. Jitter is also added to reduce the possibility that parallel requests will be retried at the same time.

ProjectApiRoot apiRoot = ApiRootBuilder
Clipboard icon

The retry implementation uses the library failsafeExternal link icon.


The UserAgentMiddleware adds a user agent header to every request. By default it submits the following data:

  • SDK version
  • JVM runtime version
  • Operating system name and version
String runtimeVersion = SystemUtils.JAVA_RUNTIME_VERSION;
String osName = SystemUtils.OS_NAME;
String osArch = SystemUtils.OS_ARCH;
String sdkVersion = BuildInfo.VERSION;
return (
userAgent +
sdkVersion +
" " +
" Java/" +
runtimeVersion +
" (" +
osName +
"; " +
osArch +
Clipboard icon


The AcceptGZipMiddleware adds an Accept-Encoding: gzip header, to enable compressing the response to reduce the data transport time.


The InternalLoggerMiddleware logs every request sent using the Java SDK. Depending on the configured logging level, the default implementation logs the request and the response.

The info level outputs the request method, URL, and response status. Using debug level, the request and response instances are logged. With trace level, it will pretty-print the request body and response. Sensitive data (such as passwords and tokens) is redacted.