Error Handling & Retry Patterns
These patterns control how Temporal retries Activities, surfaces persistent failures, and recovers from errors that require human intervention.
Patterns in this section
Fixed Count of Retries
Caps the number of Activity retry attempts to control cost when each attempt consumes a paid or limited resource.
Fixed Wall-Time Retries
Bounds the total elapsed time across all retry attempts to enforce a business SLA, regardless of how many attempts occur.
Non-Retryable Errors
Marks error types that will never succeed — such as validation failures or missing records — so Temporal fails fast instead of retrying.
Delayed Retry
Override the next retry interval for a specific failure using nextRetryDelay on ApplicationFailure. Use when an error carries information about how long to wait before retrying.
Fast/Slow Retries
Retries aggressively with a short interval first, then shifts to a long interval when fast retries are exhausted, keeping the Workflow alive until the downstream system recovers.
Retry Alerting via Metrics
Emits a custom metric from inside the Activity when the attempt count crosses a threshold, surfacing silent persistent failures to on-call teams before an SLA breach.
Resumable Activity
Parks the Workflow after retries are exhausted and waits for a human to correct the data or approve continuing, then resumes from where it left off.
Choosing a pattern
The following decision tree helps you select the appropriate retry strategy for your use case.
The following describes each decision point:
- If each attempt consumes a paid API call, a rate-limited token, or another scarce resource, use Fixed Count of Retries to cap total consumption.
- If the error is structural — a missing record, invalid input, or authorization failure — and cannot be corrected automatically, ask whether a human can fix it: if so, use Resumable Activity to park the Workflow and await a correction signal; otherwise use Non-Retryable Errors to fail fast.
- If the downstream system has a scheduled maintenance window and you know approximately how long it will be unavailable, use Delayed Retry with a fixed interval.
- If the process must resolve (one way or another) within a business SLA window such as 24 hours, use Fixed Wall-Time Retries with
ScheduleToCloseTimeout. - If you want to recover from transient errors quickly but also wait indefinitely for the downstream system to come back, use Fast/Slow Retries.
- For any long-running retry scenario, add Retry Alerting via Metrics to surface persistent failures before they breach an SLA.
How Temporal retries work
Temporal's default RetryPolicy retries Activities indefinitely with exponential backoff.
Unless you configure a policy, a failing Activity will keep retrying until the ScheduleToCloseTimeout or the Workflow itself completes.
The key RetryPolicy fields are:
| Field | Default | Effect |
|---|---|---|
MaximumAttempts | 0 (unlimited) | Caps total attempts including the first |
InitialInterval | 1 second | Delay before the first retry |
BackoffCoefficient | 2.0 | Multiplier applied after each retry |
MaximumInterval | 100× InitialInterval | Upper bound on the backoff delay |
NonRetryableErrorTypes | [] | Error types that skip retries entirely |
ScheduleToCloseTimeout is set on the Activity call options, not in RetryPolicy.
It caps the total wall-clock time from when the Activity is first scheduled to when it must complete — across all retry attempts.
Related sections
- External Interaction Patterns — heartbeating, polling, and approval gates for the external calls that fail
- Distributed Transaction Patterns — compensate completed steps when retries finally give up
- Performance & Latency Patterns — where retry configuration fits in the latency budget