Workflow error handling

FastHook separates retryable failures from terminal workflow logic. A temporary provider or transport error can retry automatically; a connected error route can handle the final failure as data; otherwise the Workflow run fails.

Failure sequence

Step fails
  → retry if the failure is retryable and attempts remain
  → otherwise follow the connected Error route
  → otherwise fail the Workflow run

The Workflow queue permits up to 10 retry decisions after the initial execution attempt for errors marked retryable. Provider Retry-After information is respected within the runtime delay limit when available.

Add an error route

1. Add a new Step after the Step that may fail.
2. Set Input from to that earlier Step.
3. Set Output to Error instead of Success.
4. Configure an alert, record, fallback Action, or Transformation using the error data.

Each Step can have one connected error route. Steps downstream of that route inherit the error branch until the graph explicitly transitions through their own outputs.

Error envelope

The error route receives normalized data instead of a successful provider output. It can include the public error code, message, failed Step identity, attempt, response status, retryability, provider, and provider-safe details. See Limits, statuses, and error codes for the exact envelope and current retry limits.

Use the data picker on the error branch. Do not map a success-only output field into error handling: normal and error ports intentionally expose different results.

Handled versus unhandled errors

When a failed Step has a matching error route, the route can continue and the overall run may succeed even though Audit retains the failed Step record. This means “Succeeded” describes completed routing, not that every provider call returned success.

Without an error route, a non-retryable failure or an exhausted retryable failure ends the run as Failed and marks unreachable Steps skipped.

Dead-letter recovery

If Workflow queue retries are exhausted, FastHook marks matching queued or running runs as Failed with workflow_delivery_exhausted. Pending or running Step records are also closed as failed so operational history does not remain stuck.

Recommended patterns

Alert and stop

Send the normalized error to a dedicated operations channel or incident system. Do not reconnect that branch to the ordinary business-success path.

Record and continue

Write failure details to a table or database, then continue only when the business process tolerates partial completion.

Compensating Action

Use an error route to undo or offset an earlier side effect. Design compensation to be idempotent because the original step or the recovery Action may be retried.

Provider fallback

Call a second provider only for specific terminal errors. Add a Filter on the error code before the fallback Action so permission or validation failures are not mistaken for temporary outages.

Debugging checklist

• Inspect the first failed Step, not only the final run message.
• Check attempt count and retryability before manually repeating an Action.
• Compare mapped input with provider-required fields and scopes.
• Confirm the error route is connected to the Error output, not Success.
• Test recovery with a controlled failure before activating the Workflow for production events.

Use Workflow Audit for evidence and Connected accounts for credential failures.