Alibaba Cloud SDK:Advanced backoff mechanism based on the throttling policy

Enable the backoff policy based on the throttling policy

By default, the throttling-based backoff policy is disabled. You can enable it by using one of the following methods:

1. Configure a retry policy.

RetryPolicy retryPolicy = RetryPolicy.builder()
                .maxNumberOfRetries(3) // The maximum number of retries.
                .maxDelayTimeMillis(20 * 1000) // The maximum retry interval. Unit: milliseconds. If the interval is exceeded, no retries are performed.
                //.retryConditions(retryConditions) // The policy that is used to trigger retries.
                .enableAliyunThrottlingControl(true) // Enable the backoff policy based on the throttling policy. 
                //.throttlingConditions(throttlingConditions) // The policy that is used to restrict retries.
                .build();

request.setSysRetryPolicy(retryPolicy);

2. Use the default retry policy.

// The default policy. The request parameter is enableAliyunThrottlingControl. The value true specifies that the backoff policy based on the throttling policy is enabled. The value false specifies that the backoff policy based on the throttling policy is disabled.
RetryPolicy retryPolicy = RetryPolicy.defaultRetryPolicy( 
true 
);

request.setSysRetryPolicy(retryPolicy);

Benefits of enabling the backoff policy based on the throttling policy

1. Reduces unnecessary retries and lowers system resource consumption.

2. Calculates more accurate backoff intervals, which improves retry success rates.

Backoff policy: Calculate backoff time based on the throttling policy

When the throttling-based backoff policy is enabled, backoff time is calculated as follows:

1. If no throttling is triggered, EqualJitter is used to calculate a retry interval.

2. If throttling is triggered, the retry interval is the larger value between the remaining time of the current throttling cycle and the EqualJitter result. If this interval exceeds the maximum retry interval, an exception is thrown and the remaining throttling cycle time is cached for use by the request-disabling policy.

Policy of disabling API requests during throttling

When the throttling-based backoff policy is enabled and throttling is triggered, the server returns remaining quota information in the response header. This information includes the remaining number of API calls and the remaining time of the current throttling cycle, reported in the "User" and "API + User" dimensions. If API calls are throttled, the remaining call count is 0.

Limit: the maximum throttling threshold. The value is of the INT type.
Time: the time span of throttling. The value is of the LONG type. Unit: milliseconds.
TimeLeft: the remaining time of the current throttling cycle. The value is of the LONG type. Unit: milliseconds.
Reset: the start time of the next throttling cycle. The value is of the LONG type and is a timestamp in milliseconds

The SDK tracks the remaining time of the current throttling cycle and blocks new calls or retries during that period. If the remaining time exceeds the maximum retry interval, an error is thrown. Otherwise, the system waits until the throttling cycle ends before initiating or retrying the call.

Enable throttling debugging

To retrieve throttling quota information without waiting for throttling to be triggered, set X-RateLimit-Mode to debug in the request header.

request.putHeadParameter("X-RateLimit-Mode", "debug");