Failures and Retries

What the engine does when a step fails - the retry it performs on its own, the error branch you can author, and what is not available from your product.

When a step in a connected user's workflow fails, the engine does not give up immediately. Knowing exactly what it does - and what it does not - is what lets you tell a customer whether a failure was transient or final.

What happens on a failed step

The step is marked failed and, if it has retries left, the engine re-dispatches it.
Each retry increments the attempt count and waits longer than the last.
When retries are exhausted, the failure propagates: parent steps are marked failed and the run ends as FAILED.
Unless the step sits inside an on-error branch, in which case that branch runs instead and the workflow continues.

A run ends in one of five states: CREATED, STARTED, COMPLETED, FAILED, STOPPED.

Retries

Retries are off by default. A step retries only if its workflow task sets maxRetries:

{
  "label": "Create contact",
  "name": "createContact",
  "type": "hubspot/v1/createContact",
  "maxRetries": 3
}

The delay between attempts grows with each one - roughly two seconds, then four, then six. That backoff is fixed: maxRetries is the only retry setting a workflow definition can express, so the delay is not tunable per step.

Retry re-runs the step, not the workflow

A retry re-dispatches that one step with the same input. Steps that already succeeded do not run again. This makes retries safe for a failed write only if the step itself is idempotent - a retried "create" against a provider that does not deduplicate can produce two records.

Retries suit transient faults: a provider timeout, a 5xx, a rate-limit rejection. They do not help with bad input or a revoked credential, which will fail identically every attempt and only delay the final failure.

Error branches

For failures you want to handle rather than retry, wrap the step in an on-error branch. The error is captured and the branch runs, so the workflow can notify someone, write a fallback record, or exit cleanly instead of ending as FAILED. This is authored in the workflow itself and applies to every connected user running that workflow.

What your product can see

Every attempt is recorded. A run's execution history shows each step with its inputs, outputs, and the error that failed it, including the retried attempts - so "it failed three times two seconds apart" is visible rather than inferred. See Workflow Executions.

Failure notifications

A failed run does raise a notification: subscribe to the JOB_FAILED event in Notifications, which documents the available events and delivery types. This covers embedded runs as well as automation ones - a connected user's run is an ordinary job, and the same event fires for it.

Three properties of that mechanism decide whether it fits what you want to build:

The subscription is instance-wide, per event. It fires for every failed job in the deployment. There is no filter by integration, workflow, or connected user, so you cannot subscribe on behalf of one customer.
The message identifies the job, not the customer. The notification is rendered from the job's label and id. It does not carry the connected user, the integration, or the error, so mapping an alert back to a customer means looking the execution up.
It notifies you, not your users. The destination is a channel your team owns. There is no per-customer destination.

So it works well as an operational alert for your own team. To surface a failure inside your product, against the right customer, keep polling executions and raise the alert yourself.

What is not available yet

No replay from your product

There is no embedded endpoint to re-run a failed execution. ByteChef can restart a job internally, but that surface is not part of the embedded API, so you cannot offer your customers a "retry this run" button. Today the options are to have the trigger fire again, or to author retries into the workflow up front.