AWS Step Functions & EventBridge Support
AWS Step Functions error handling: Retry and Catch.
By default, any error in a Step Functions state fails the whole execution. Retry and Catch let a workflow recover from transient errors and route real failures to cleanup or alerting. We design them per state so failures are handled on purpose, not by accident.
When You Need This
The situations where this work pays for itself.
Signs it is time
- Executions fail on a single transient Lambda or API error
- Failed executions are discovered by users, not by alerts
- A failure partway through leaves data half-written
- Retries cause duplicates or retry storms
- Tasks hang because no timeout is set
What you get
- State machine definitions with Retry and Catch per task
- A failure catalog listing which errors retry and which do not
- Alarms and notifications for failed and timed out executions
- Test cases that exercise each failure path
How we do it
A clear, safe process you can follow along with.
1. Review failure history
We list failed executions and group them by error name and state using execution history and CloudWatch metrics, so we know which errors are transient and which are bugs.
2. Add Retry for transient errors
For Task states we add a Retry block with ErrorEquals, IntervalSeconds, MaxAttempts and BackoffRate, and JitterStrategy FULL to avoid retry bursts. Lambda service errors such as Lambda.ServiceException and Lambda.TooManyRequestsException are common matches.
3. Order the matchers carefully
Retriers and catchers are evaluated in order, and States.ALL must be last. We keep specific errors first and avoid retrying errors that can never succeed, such as validation failures.
4. Add Catch with context preserved
A Catch block sends failures to a handler state. Set ResultPath on the catcher so the original input is kept alongside the error, otherwise the error output replaces the state input.
5. Set timeouts and heartbeats
TimeoutSeconds stops tasks that hang, and HeartbeatSeconds detects stuck long-running activities or callback tasks. Without them an execution can wait a very long time.
6. Design compensation and alerts
For multi-step writes we add compensating steps in the Catch path, publish failures to SNS or EventBridge, and alarm on ExecutionsFailed and ExecutionsTimedOut.
7. Test failure paths
We force each error with test inputs or by temporarily failing a Lambda, and confirm the workflow retries, catches and notifies as designed.
Mistakes we help you avoid
Common ways this goes wrong, and what we do instead.
Catching everything and swallowing it
A Catch that continues quietly hides real bugs. Always record and alert.
Retrying non-idempotent tasks
A retried charge or email may run twice. Make the task idempotent first.
No timeout on tasks
A hung task blocks the execution and costs nothing visible until someone notices.
Losing input on catch
Without a ResultPath, the handler cannot see what failed.
Frequently Asked Questions
What is the difference between Retry and Catch?
Retry runs the same state again after an error. Catch moves the execution to another state when retries are exhausted or not applicable.
What does States.ALL match?
It matches all error names except States.DataLimitExceeded, which cannot be retried or caught by it. It must appear last in the list.
Does Step Functions retry by default?
No. Task states do not retry unless you add a Retry block, so one transient error fails the execution.
Want Help With AWS Step Functions error handling: Retry and Catch?
Schedule an appointment. Tell us about your environment and we will outline the safest, highest-value approach.
Schedule Appointment › No commitment required