Skip to main content

Retry Policies

A Retry Policy works in cooperation with the timeouts to provide fine controls to optimize the execution experience.

A Retry Policy is a collection of attributes that instructs the Temporal Server how to retry a failure of a Workflow Execution or an Activity Task ExecutionLink preview iconWhat is an Activity Task Execution?

An Activity Task Execution occurs when a Worker uses the context provided from the Activity Task and executes the Activity Definition.

Learn more. (Retry Policies do not apply to Workflow Task ExecutionsLink preview iconWhat is a Workflow Task Execution?

A Workflow Task Execution occurs when a Worker picks up a Workflow Task and uses it to make progress on the execution of a Workflow Definition.

Learn more, which always retry indefinitely.)

Diagram that shows the retry interval and its formula

Diagram that shows the retry interval and its formula

Default behavior​

Custom Retry Policy​

To use a custom Retry Policy, provide it as an options parameter when starting a Workflow Execution or Activity Execution. Only certain scenarios merit starting a Workflow Execution with a custom Retry Policy, such as the following:

Properties​

Default values for Retry Policy​

Initial Interval     = 1 second
Backoff Coefficient  = 2.0
Maximum Interval     = 100 × Initial Interval
Maximum Attempts     = ∞
Non-Retryable Errors = []

Initial Interval​

  • Description: Amount of time that must elapse before the first retry occurs.
    • The default value is 1 second.
  • Use case: This is used as the base interval time for the Backoff Coefficient to multiply against.

Backoff Coefficient​

  • Description: The value dictates how much the retry interval increases.
    • The default value is 2.0.
    • A backoff coefficient of 1.0 means that the retry interval always equals the Initial Interval.
  • Use case: Use this attribute to increase the interval between retries. By having a backoff coefficient greater than 1.0, the first few retries happen relatively quickly to overcome intermittent failures, but subsequent retries happen farther and farther apart to account for longer outages. Use the Maximum Interval attribute to prevent the coefficient from increasing the retry interval too much.

Maximum Interval​

  • Description: Specifies the maximum interval between retries.
  • Use case: This attribute is useful for Backoff Coefficients that are greater than 1.0 because it prevents the retry interval from growing infinitely.

Maximum Attempts​

  • Description: Specifies the maximum number of execution attempts that can be made in the presence of failures.
    • The default is unlimited.
    • If this limit is exceeded, the execution fails without retrying again. When this happens an error is returned.
    • Setting the value to 0 also means unlimited.
    • Setting the value to 1 means a single execution attempt and no retries.
    • Setting the value to a negative integer results in an error when the execution is invoked.
  • Use case: Use this attribute to ensure that retries do not continue indefinitely. However, in the majority of cases, we recommend relying on the Workflow Execution Timeout, in the case of Workflows, or Schedule-To-Close Timeout, in the case of Activities, to limit the total duration of retries instead of using this attribute.

Non-Retryable Errors​

  • Description: Specifies errors that shouldn't be retried.
  • Use case: There may be errors that you know of that should not trigger a retry. In this case, you can specify them such that, if they occur, the given execution is not retried.

Retry interval​

The wait time before a retry is the retry interval. A retry interval is the smaller of two values:

Event History​

There are some subtle nuances to how Events are recorded to an Event History when a Retry Policy comes into play.