An AWS Step Functions Task state calls a worker that sometimes dies without reporting back, leaving executions stuck for hours. How do TimeoutSeconds and HeartbeatSeconds address this, and how do they differ?

## The failure being solved A Step Functions `Task` state waits for something to report back. If that something never does — the container was terminated, the process segfaulted, the machine lost its network — the state waits. With no timeout configured, it waits until the execution itself expires, and a Standard workflow's maximum execution duration is measured in months. The observable symptom is an execution sitting on one state indefinitely, with nothing failing, nothing alarming, and nothing retrying, because from Step Functions' point of view the task simply has not finished yet. Both mechanisms turn that silence into an error name, which is what makes the rest of the error-handling machinery — retriers, catchers, a compensating branch — able to act. ## TimeoutSeconds: the total budget `TimeoutSeconds` is a field on the `Task` state giving the maximum wall-clock time from when the task starts to when it reports success. Exceed it and the state fails with `States.Timeout`, which you can name in `ErrorEquals` like any other error. ```json "ConvertVideo": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "TimeoutSeconds": 3600, "HeartbeatSeconds": 60, "Retry": [{ "ErrorEquals": ["States.HeartbeatTimeout"], "MaxAttempts": 2 }], "Next": "Publish" } ``` There is also a top-level `TimeoutSeconds` on the state machine definition itself, bounding a whole execution. Setting it is cheap insurance against a workflow that gets stuck in a loop or on a state you forgot to bound. ## HeartbeatSeconds: the liveness clock `HeartbeatSeconds` sets the maximum interval Step Functions will tolerate between liveness signals. The worker is responsible for sending them: it calls the `SendTaskHeartbeat` API with the task token it was handed, on whatever cadence it chooses, as long as the gap stays under `HeartbeatSeconds`. Miss the window and the task fails with `States.HeartbeatTimeout`. This only makes sense where a worker holds a task token and can call back — activities polled with `GetActivityTask`, and service integrations using the `.waitForTaskToken` pattern. There is nothing to heartbeat in a plain request/response task that returns in one call. `HeartbeatSeconds` must be less than `TimeoutSeconds`; a heartbeat window as long as the whole budget detects nothing. ## Why you want both The two clocks answer different questions, and the gap between them is the entire value: - `TimeoutSeconds` asks *"is this job taking unreasonably long?"* - `HeartbeatSeconds` asks *"is anybody still working on it?"* A video transcode may legitimately need an hour, so the budget has to be an hour. If the transcoding worker crashes ninety seconds in, a one-hour timeout means fifty-eight minutes of an execution that is already dead. A sixty-second heartbeat surfaces it almost immediately, so the retrier can hand the work to a healthy worker while the customer is still on the page. Notice in the snippet above that the retrier names `States.HeartbeatTimeout` specifically — a crashed worker is worth retrying, whereas a genuine `States.Timeout` may mean the input is simply too large and retrying will only time out again. ## The fact people miss: the work does not stop When the clock expires, Step Functions stops waiting. It does **not** reach out and kill the worker. An external activity worker or an already-running function invocation carries on, unaware, and may complete its side effects after the state has already failed and the workflow has moved to a compensating branch. If a retrier then hands the same input to a second worker, both are doing the job. This has two consequences worth volunteering in an interview. First, downstream operations under a timed-out task need to be idempotent, keyed on something stable — the execution name is available on the context object as `$$.Execution.Name` and makes a natural idempotency key that survives across retries of the same execution. Second, a worker that finishes late and calls `SendTaskSuccess` for a task that already timed out will get an error rather than resurrecting the execution, so it must handle that path rather than assuming success. ## Choosing the numbers Set `TimeoutSeconds` from the honest p99 of the work plus headroom, not from the average, or you will manufacture failures on the tail. Set `HeartbeatSeconds` from how quickly you need to detect a dead worker, and make sure the worker's heartbeat cadence has room for a couple of missed sends inside that window. Where the right budget depends on the payload — a small file versus a large one — `TimeoutSecondsPath` and `HeartbeatSecondsPath` read the values from the state's input instead of hard-coding them.