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 one failure's retry interval with nextRetryDelay on ApplicationFailure, matching the wait time the error reports.
Fast/Slow Retries
Retries fast with a short interval first, then shifts to a slow, unlimited interval so the Workflow outlasts an extended downstream outage.
Retry Alerting via Metrics
Emits a metric from the Activity when attempts cross a threshold, so on-call teams see persistent failures 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