Sleeping and retrying
This guide details how to sleep a Workflow and/or configure retries for a Workflow step.
You can set a Workflow to sleep as an explicit step, which can be useful when you want a Workflow to wait, schedule work ahead, or pause until an input or other external state is ready.
Use step.sleep
to have a Workflow sleep for a relative period of time:
The second argument to step.sleep
accepts both number
(seconds) or a human-readable format, such as “1 minute” or “26 hours”. The accepted units for step.sleep
when used this way are as follows:
Use step.sleepUntil
to have a Workflow sleep to a specific Date
: this can be useful when you have a timestamp from another system or want to “schedule” work to occur at a specific time (e.g. Sunday, 9AM UTC).
You can also provide a Unix timestamp (seconds since the Unix epoch) directly to sleepUntil
.
Each call to step.do
in a Workflow accepts an optional StepConfig
, which allows you define the retry behaviour for that step.
If you do not provide your own retry configuration, Workflows applies the following defaults:
When providing your own StepConfig
, you can configure:
- The total number of attempts to make for a step
- The delay between attempts (accepts both
number
(ms) or a human-readable format) - What backoff algorithm to apply between each attempt: any of
constant
,linear
, orexponential
- When to timeout (in duration) before considering the step as failed (including during a retry attempt)
For example, to limit a step to 10 retries and have it apply an exponential delay (starting at 10 seconds) between each attempt, you would pass the following configuration as an optional object to step.do
:
You can also force a Workflow instance to fail and not retry by throwing a NonRetryableError
from within the step.
This can be useful when you detect a terminal (permanent) error from an upstream system (such as an authentication failure) or other errors where retrying would not help.
The Workflow instance itself will fail immediately, no further steps will be invoked, and the Workflow will not be retried.
Any uncaught exceptions that propagate to the top level, or any steps that reach their retry limit, will cause the Workflow to end execution in an Errored
state.
If you want to avoid this, you can catch exceptions emitted by a step
. This can be useful if you need to trigger clean-up tasks or have conditional logic that triggers additional steps.
To allow the Workflow to continue its execution, surround the intended steps that are allowed to fail with a try-catch
block.