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;


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(


PolicyMiddleware and PolicyBuilder allow the combination of different policies for failing requests (for example, retrying).

When retrying, the middleware uses an exponential backoff strategy which increases the wait time before each retry to avoid overwhelming the API. Jitter is also added to reduce the possibility of parallel requests.

ProjectApiRoot apiRoot = ApiRootBuilder
.withPolicies(policyBuilder ->
policyBuilder.withRetry(retry ->

PolicyMiddleware uses the library failsafe.


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 +


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.