Error handling - Amazon Step Functions
Retry on errorsCatch errorsTimeoutsHeartbeat
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Error handling

By default, when a state reports an error, Step Functions causes the execution to fail entirely. For actions and some flow states, you can configure how Step Functions handles errors. Even if you have configured error handling, some errors may still cause an execution to fail. For more information, see Error handling in Step Functions. In Workflow Studio, configure error handling in the the Error handling panel.

Error handling options

Retry on errors

You can add one or more rules to action states and the Parallel flow state to retry the task when an error occurs. These rules are called retriers. To add a retrier, choose Add new retrier, then configure its options:

  • (Optional) The Comment field can be used to add your own comment. It will not affect the workflow, but can be used to annotate your workflow.

  • Choose an Error that will trigger the retrier, or enter your own custom error name.

  • (Optional) Set an Interval. This is the time in seconds before Step Functions make its first retry. Additional retries will follow at intervals that you can configure with Max attempts and Backoff rate.

  • (Optional) Set Max attempts. This is the maximum number retries before Step Functions will cause the execution to fail.

  • (Optional) Set the Backoff rate. This is a multiplier that determines by how much the retry interval will increase with each attempt.

Catch errors

You can add one or more rules to action states and to the Parallel and Map flow state to catch an error. These rules are called catchers. To add a catcher, choose Add new catcher, then configure its options:

  • (Optional) The Comment field can be used to add your own comment. It will not affect the workflow, but can be used to annotate your workflow.

  • Choose an Error that will trigger the catcher, or enter your own custom error name.

  • Choose an Fallback state. This is the state that the workflow will move to next, after an error is caught.

  • (Optional) Add a ResultPath to add the error to the original state input. The ResultPath must be in valid JSONPAth syntax. This will be sent to the fallback state.

Timeouts

You can configure a timeout for action states to set the maximum number of seconds your state can run before it fails. Use timeouts to prevent stuck executions. To configure a timeout, enter the number of seconds your state should wait before the execution fails. For more information, see TimeoutSeconds in the Task section.

Heartbeat

You can configure a heartbeat or periodic notification sent by your task. If you set a heartbeat interval, and your state doesn't send heartbeat notifications in the configured intervals, the task is marked as failed. To configure a heartbeat, set a positive, non-zero integer number of seconds. For more information, see HeartBeatSeconds in the Task section.

Note

Not all error handling options are available for all states. Lambda Invoke has one retrier configured by default.