Retry policies

Retry policy parameters control how activities and workflow tasks retry after failures. Configure these parameters to handle transient failures gracefully with exponential backoff.

initial_intervaltimedelta

Optional

Delay before the first retry attempt. The system waits this duration after the initial failure before attempting the first retry.

Default: 1 second

Example:timedelta(seconds=2)

backoff_coefficientfloat

Optional

Multiplier applied to the interval after each retry. Temporal uses exponential backoff by multiplying the previous interval by this coefficient to calculate the next retry delay.

Default: 2.0

Example:2.5

maximum_intervaltimedelta

Optional

Cap on exponential backoff delay. When exponential backoff calculates an interval longer than this value, the system uses this maximum instead. Prevents unbounded wait times between retries.

Default: 100 seconds

Example:timedelta(seconds=60)

maximum_attemptsint

Optional

Total attempts including the initial execution. When set to 0, the activity retries indefinitely until it succeeds or hits a non-retryable error.

Default: 0 (unlimited)

Examples:

• 5
• 10
• 0

non_retryable_error_typeslist[str]

Optional

List of error types or names that fail immediately without retrying. When an activity raises an error matching any entry in this list, Temporal marks it as failed and doesn't attempt retries. Use this to prevent retries for permanent failures like validation errors.

Examples:

• ValueError
• AuthenticationError
• InvalidConfigurationError

Usage example

This example invokes an activity with a retry policy configured. If the activity fails, Temporal waits 1 second before the first retry (initial_interval). Each subsequent retry doubles the wait time (backoff_coefficient of 2.0) up to a maximum of 30 seconds (maximum_interval). The activity attempts up to 5 times total (maximum_attempts). If the activity raises a ValueError, it fails immediately without retrying (non_retryable_error_types).

from datetime import timedelta
from temporalio.common import RetryPolicy

result = await workflow.execute_activity(
    my_activity,
    start_to_close_timeout=timedelta(seconds=10),
    retry_policy=RetryPolicy(
        initial_interval=timedelta(seconds=1),
        backoff_coefficient=2.0,
        maximum_interval=timedelta(seconds=30),
        maximum_attempts=5,
        non_retryable_error_types=["ValueError"],
    ),
)

See also

• Retry strategies: Understand the concepts behind retry strategies and how they work with timeouts and heartbeats