Skip to main content
Version: 0.8.x



Retry helps in applying a retry policy in order to try and transform failed requests into successful ones. What is considered as success can be defined by specific criteria. The Retry remedy plugin supports custom configuration for wait times between retry attempts.

In case the retry attempts sequence did not conclude with a successful response, the last failed response will be returned to the caller.

Client-Side Retries

The Retry remedy plugin is designed to offload required retry attempts to the client-side rather than handling them within Lunar Proxy itself. This is done in order to avoid client-side timeouts.

For this purpose, the Retry remedy plugin works tightly alongside Lunar Interceptors, which in turn react to specific internal headers handed over by Lunar Proxy in case a retry attempt is required.


- name: Retry
enabled: true
attempts: <attempts>
initial_cooldown_seconds: <initial_cooldown_seconds>
cooldown_multiplier: <cooldown_multiplier>
from: <min_status_code>
to: <max_status_code>

The following configuration options are available for this remediation plugin:

ParameterExample ValuePossible ValuesDescription
attempts3Any positive integerThe maximal number of retry attempts
initial_cooldown_seconds1Any positive integerThe initial number of seconds to wait before a retry attempt
cooldown_multiplier2Any positive integerThe multiplier to apply for number of seconds to wait between attempts. Use 1 to apply constant wait time between requests
min_status_code500Any positive integerThe lower end of status codes to apply retry upon. Inclusive
max_status_code599Any positive integer above min_status_codeThe higher end of status codes to apply retry upon. Inclusive


- url:{id}
method: GET
- name: Retry
enabled: true
attempts: 3
initial_cooldown_seconds: 1
cooldown_multiplier: 2
from: 500
to: 599

In the example above, the plugin will perform 3 or less retry attempts until a non-5XX response comes back from the API provider. In case all 3 retry attempts are required, the wait times after each attempt would be:

AttemptWait Time
#11 second (1 X 1)
#22 second (1 X 2)
#34 second (1 X 4)

This is because initial_cooldown_seconds is set to 1 and cooldown_multiplier is set to 2.


Currently, it is only possible to configure retry conditions regarding status code range. Since the range is inclusive on both ends, specifying the same status code in both from and to fields would effectively apply the remedy for that specific status code only.

Use Cases

  • Artificially Increasing Provider's Availability: As any other web service, API providers might experience temporary outages that result in an undesired server-side error (5XX). These can be mitigated by a simple delayed retry.

  • Chaining With Throttling Remedy Plugins: The purpose of Lunar's various throttling remedy plugins is to return an internal, initiated Too Many Requests response. Thus, chaining a retry remedy after these can prove beneficial in order to transform requests into an eventual successful response while avoiding exceeding rate limits and being punished with exponential backoff Retry-After times.

Click me for guidance 😀