---
title: "RetryConfig"
description: "RetryConfig"
url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/java/reference/retryconfig"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-18"
---

# RetryConfig

## RetryConfig

RetryConfig sets the retry behavior of the Java Management SDK for a request that fails with a transient HTTP status or a socket timeout. Use this class to

*   change the number of retries, or turn retries off
*   change the wait between retries, with a fixed delay or with [RetryDelayOptions](/docs/developers/sdks/content-management-sdk/java/reference/retrydelayoptions)
*   choose which failures trigger a retry, with your own condition

Get a builder with RetryConfig.builder() or new RetryConfig.Builder(), set the values, and call [build](/docs/developers/sdks/content-management-sdk/java/reference/retryconfig#retryconfig-build). [defaultConfig](/docs/developers/sdks/content-management-sdk/java/reference/retryconfig#retryconfig-defaultconfig) returns the default configuration. Pass the configuration to the [setRetryConfig](/docs/developers/sdks/content-management-sdk/java/reference/contentstackbuilder#contentstackbuilder-setretryconfig) method of Contentstack.Builder before you build the client. A RetryConfig object has no setters, so its values stay fixed after build.

## build

build creates a RetryConfig object from the values set on the builder.

```
Returns: RetryConfig. A new retry configuration.
ValidationThere is no client-side validation.build does not throw.BehaviorWhen the builder holds no retry condition, build sets the default condition, DefaultRetryCondition.The new object copies the values from the builder. A later setter call on the builder does not change it.RetryConfig has no setters, so its values stay fixed after build.Pass the result to the setRetryConfig method of Contentstack.Builder before you call build() on that builder. A client keeps the configuration it receives at that point.ExampleBasic usage: build a configuration and create a client with itimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class BuildRetryConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(2)
                .retryDelay(500)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig() == retryConfig); // true
    }
}
```

## builder

builder creates a builder for a RetryConfig object, preset with the default values.

```
Returns: Builder. A new retry configuration builder.
ValidationThere is no client-side validation.builder does not throw.Behaviorbuilder is a static method of RetryConfig. new RetryConfig.Builder() also returns a new builder with the same preset values.The returned type is RetryConfig.Builder.A new builder holds a retry limit of 3 and a fixed delay of 300 ms. It holds no retry condition and no delay options. build fills a missing retry condition with the default one.ExampleBasic usage: start a retry configurationimport com.contentstack.cms.core.RetryConfig;

public class StartRetryConfig {
    public static void main(String[] args) {
        RetryConfig.Builder builder = RetryConfig.builder();
        RetryConfig retryConfig = builder.retryLimit(5).build();
        System.out.println(retryConfig.getRetryLimit()); // 5
        System.out.println(retryConfig.getRetryDelay()); // 300, the default
    }
}
```

## defaultConfig

defaultConfig creates a RetryConfig with the default values, the same configuration that every client starts with.

```
Returns: RetryConfig. A new retry configuration with the default values.
ValidationThere is no client-side validation.defaultConfig does not throw.BehaviordefaultConfig is a static method of RetryConfig. It returns the same values as RetryConfig.builder().build().The default values are a retry limit of 3, a fixed delay of 300 ms, the default retry condition and no delay options.The default retry condition retries a socket timeout and the statuses 408, 429, 500, 502, 503 and 504.Each call returns a new object.ExampleBasic usage: read the default valuesimport com.contentstack.cms.core.RetryConfig;

public class ReadDefaultRetryConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.defaultConfig();
        System.out.println(retryConfig.getRetryLimit());          // 3
        System.out.println(retryConfig.getRetryDelay());          // 300
        System.out.println(retryConfig.getRetryDelayOptions());   // null
        System.out.println(retryConfig.getRetryCondition().shouldRetry(429, null)); // true
    }
}
```

## getRetryCondition

getRetryCondition returns the rule that decides whether the SDK retries a failed request.

```
Returns: RetryCondition. The rule that decides which failures to retry.
ValidationThere is no client-side validation.getRetryCondition does not throw.BehaviorNever returns null. Without a condition from the retryCondition method, it returns the shared DefaultRetryCondition instance.Call shouldRetry(statusCode, error) on the result to check a status. Pass 0 and the exception for a socket timeout.ExampleBasic usage: check which statuses the SDK retriesimport com.contentstack.cms.core.RetryCondition;
import com.contentstack.cms.core.RetryConfig;

public class CheckRetryCondition {
    public static void main(String[] args) {
        RetryCondition condition = RetryConfig.defaultConfig().getRetryCondition();
        int[] statuses = {200, 404, 408, 429, 500, 503};
        for (int status : statuses) {
            System.out.println(status + " retried: " + condition.shouldRetry(status, null));
        }
    }
}
```

## getRetryDelay

getRetryDelay returns the fixed wait, in milliseconds, that the SDK uses when no delay options decide the wait.

```
Returns: long. The fixed wait between retries in milliseconds.
ValidationThere is no client-side validation.getRetryDelay does not throw.BehaviorThe default is 300.The SDK ignores this value while the delay options hold a custom backoff function or a base greater than 0. Check with the getRetryDelayOptions method.ExampleBasic usage: read the fixed delayimport com.contentstack.cms.core.RetryConfig;

public class ReadRetryDelay {
    public static void main(String[] args) {
        System.out.println(RetryConfig.builder().retryDelay(1200).build().getRetryDelay()); // 1200
        System.out.println(RetryConfig.defaultConfig().getRetryDelay());                    // 300
    }
}
```

## getRetryDelayOptions

getRetryDelayOptions returns the delay options that [retryDelayOptions](/docs/developers/sdks/content-management-sdk/java/reference/retryconfig#retryconfig-retrydelayoptions) set.

```
Returns: RetryDelayOptions. The delay options, or null.
ValidationThere is no client-side validation.getRetryDelayOptions does not throw.BehaviorReturns null by default. Every retry then waits the fixed delay from the getRetryDelay method.Read the values with the getBase and getCustomBackoff methods of RetryDelayOptions.ExampleBasic usage: read the delay optionsimport com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;

public class ReadDelayOptions {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryDelayOptions(RetryDelayOptions.builder().base(250).build())
                .build();
        RetryDelayOptions delayOptions = retryConfig.getRetryDelayOptions();
        if (delayOptions != null) {
            System.out.println(delayOptions.getBase()); // 250
        }
        System.out.println(RetryConfig.defaultConfig().getRetryDelayOptions()); // null
    }
}
```

## getRetryLimit

getRetryLimit returns the maximum number of times the SDK retries a failed request after the first attempt.

```
Returns: int. The maximum number of retries.
ValidationThere is no client-side validation.getRetryLimit does not throw.BehaviorThe default is 3. The SDK then sends up to four attempts.The value is 0 or more, because the retryLimit method rejects a negative value.0 means the SDK retry is off.ExampleBasic usage: read the retry limitimport com.contentstack.cms.core.RetryConfig;

public class ReadRetryLimit {
    public static void main(String[] args) {
        System.out.println(RetryConfig.builder().retryLimit(6).build().getRetryLimit()); // 6
        System.out.println(RetryConfig.defaultConfig().getRetryLimit());                 // 3
    }
}
```

## retryCondition

retryCondition sets your own rule that decides whether the SDK retries a failed request.

```
Returns: Builder. The same builder, for chaining.
ValidationThere is no client-side validation. retryCondition(null) does not throw, and build then uses the default condition.An exception that your condition throws reaches your code from execute().BehaviorRetryCondition is a functional interface in com.contentstack.cms.core with one method, boolean shouldRetry(int statusCode, Throwable error). The SDK passes the two arguments below:statusCode: the HTTP status of the response, or 0 for a socket timeout.error: the java.net.SocketTimeoutException for a socket timeout, otherwise null.The SDK asks the condition only about a response or a socket timeout. Other network errors, such as a refused connection, reach your code as an IOException from execute() without a retry.For a client without Open Authorization (OAuth), the SDK asks the condition about every response, including a successful one. Return false for a 2xx status, or the SDK sends a successful request again until it reaches the retry limit.For a client that uses OAuth, the SDK asks the condition only about a response that is not 2xx. A 401 response with a refresh token available makes the SDK refresh the token and retry before it asks the condition.Without a condition, the SDK uses DefaultRetryCondition, which returns true for 0, 408, 429, 500, 502, 503 and 504. Call DefaultRetryCondition.getInstance().shouldRetry(statusCode, error) inside your condition to keep those defaults.ExampleBasic usage: retry only rate limits and timeoutsimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class RetryRateLimitsOnly {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                // 0 is a socket timeout. Every other status, including 2xx, returns false.
                .retryCondition((statusCode, error) -> statusCode == 0 || statusCode == 429)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryCondition().shouldRetry(503, null)); // false
    }
}Extend the defaults: also retry a conflict responseimport com.contentstack.cms.core.DefaultRetryCondition;
import com.contentstack.cms.core.RetryCondition;
import com.contentstack.cms.core.RetryConfig;

public class ExtendDefaultCondition {
    public static void main(String[] args) {
        RetryCondition condition = (statusCode, error) ->
                statusCode == 409 || DefaultRetryCondition.getInstance().shouldRetry(statusCode, error);
        RetryConfig retryConfig = RetryConfig.builder().retryCondition(condition).build();

        System.out.println(retryConfig.getRetryCondition().shouldRetry(409, null)); // true
        System.out.println(retryConfig.getRetryCondition().shouldRetry(200, null)); // false
    }
}
```

Rule that returns true to retry. Unset, the SDK uses DefaultRetryCondition.

## retryDelay

retryDelay sets the fixed wait, in milliseconds, before each retry when no delay options decide the wait.

```
Returns: Builder. The same builder, for chaining.
ValidationThrows IllegalArgumentException if retryDelay is below 0, because a wait cannot be negative. The exception comes from retryDelay itself, at the call, and the builder keeps its previous value.0 is valid. The SDK then retries with no wait.BehaviorThe default is 300 ms.The SDK uses this value only when no delay options decide the wait. Delay options decide it when they hold a custom backoff function or a base greater than 0. See the RetryDelayOptions class.Every retry waits the same time. For a wait that grows on each retry, use the retryDelayOptions method.ExampleBasic usage: wait one second before each retryimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class FixedRetryDelay {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(3)
                .retryDelay(1000)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryDelay()); // 1000
    }
}
```

Fixed wait before each retry, in milliseconds. Unset, the builder holds 300.

## retryDelayOptions

retryDelayOptions attaches delay options that make the wait grow on each retry or follow your own function.

```
Returns: Builder. The same builder, for chaining.
ValidationThere is no client-side validation. retryDelayOptions(null) removes earlier options, and every retry then waits the fixed delay.BehaviorThe SDK picks each wait from the first of the three rules below that matches:1. The custom backoff function of the options, when set. 2. The base of the options × the retry number, when the base is greater than 0. The retry number starts at 1. 3. The fixed delay from the retryDelay method, 300 ms by default.
The RetryDelayOptions class page lists the waits for each option.ExampleBasic usage: grow the wait by 500 ms on each retryimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;

public class LinearBackoffConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(4)
                .retryDelayOptions(RetryDelayOptions.builder().base(500).build()) // 500, 1000, 1500, 2000 ms
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryDelayOptions().getBase()); // 500
    }
}
```

Linear step or custom function for each wait. Unset, the builder holds null.

## retryLimit

retryLimit sets the maximum number of times the SDK retries a failed request after the first attempt.

```
Returns: Builder. The same builder, for chaining.
ValidationThrows IllegalArgumentException if retryLimit is below 0, because a retry count cannot be negative. The exception comes from retryLimit itself, at the call, and the builder keeps its previous limit.There is no upper limit. A high limit with a long wait can block the calling thread for a long time.BehaviorThe limit counts retries, not attempts. The SDK sends up to retryLimit + 1 attempts, so the default of 3 sends up to four attempts.0 turns the SDK retry off. The SDK then sends one attempt.For a client that uses Open Authorization (OAuth), 0 also stops the SDK from refreshing the access token after a 401 response.Known issue: In 1.16.0, a client that uses OAuth loses the body of an error response it does not retry, such as 404, while retries remain. The SDK closes the response before it returns it, so execute() throws an exception instead of returning the error response. To read error responses on such a client, set retryLimit(0) and retry in your own code.The limit applies to every request that the client sends.ExampleBasic usage: allow five retriesimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class AllowFiveRetries {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder().retryLimit(5).build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryLimit()); // 5
    }
}Error handling: reject a negative limitimport com.contentstack.cms.core.RetryConfig;

public class RejectRetryLimit {
    public static void main(String[] args) {
        RetryConfig.Builder builder = RetryConfig.builder();
        try {
            builder.retryLimit(-1);
        } catch (IllegalArgumentException e) {
            // Thrown at the call for a limit below 0
            System.out.println("Invalid retry limit: " + e.getMessage());
        }
        System.out.println(builder.build().getRetryLimit()); // 3, the default, unchanged
    }
}Edge case: turn the SDK retry offimport com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class TurnRetryOff {
    public static void main(String[] args) {
        // One attempt per request, no retries
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(RetryConfig.builder().retryLimit(0).build())
                .build();
        System.out.println(client.getRetryConfig().getRetryLimit()); // 0
    }
}
```

Maximum retries after the first attempt. Unset, the builder holds 3.

retryLimit, getRetryLimit. Maximum number of retries after the first attempt.

retryDelay, getRetryDelay. Fixed wait before each retry, in milliseconds.

retryCondition, getRetryCondition. Rule that decides which failures to retry.

retryDelayOptions, getRetryDelayOptions. Linear step or custom function for each wait.

## RetryConfig | Java Management SDK | Contentstack

The RetryConfig class in the Java Management SDK sets how many times the SDK retries a failed request, the wait between retries, and which failures trigger one.