Skip to main content

Error handling & retries

Every step in a Tool has configurable retry and error handling behavior. Together, these decide what happens when the step fails.

Both settings live on the step's side panel.

Retry configuration​

Retry toggle​

A single toggle: Enable Retry for Failure.

  • When disabled, no retries happen. The step fails on the first error.
  • When enabled, the retry fields appear and the step retries on failure based on your settings.

Max retries​

A numeric input for the maximum number of retry attempts.

  • Minimum: 1
  • Maximum: 10

If retries exceed Max retries without success, the step's failure is handled by the Error Handling setting (see below).

Retry delay​

A numeric input for the delay (in milliseconds) between retry attempts.

  • Minimum: 100 ms
  • Maximum: 5000 ms

Retries use a fixed delay — there's no exponential backoff at the no-code level.

Error handling — four modes​

The Error Handling dropdown chooses what happens after retries are exhausted (or if retries are disabled and the step errors immediately).

1. Stop Workflow (default)​

  • The step stops execution immediately.
  • The entire workflow is marked as failed.

Use when an error in this step means the whole run is invalid.

2. Continue Workflow with Error Message​

  • The step is skipped.
  • The step's output captures the error message.
  • The workflow continues normally to the next step.

Use when downstream steps can handle a missing/empty result gracefully — e.g., a Web Research step where you can fall back to an LLM's own knowledge if web search fails.

3. Fallback Value​

  • The step's output variables are set to user-defined fallback values on failure.
  • In the side panel, the step's expected output variables (based on the tool/step output schema) are listed; you fill in fallback values for each.
  • Downstream steps consume the fallback values as if they were the step's real output.

Use when the step's output shape must be present and structured, but the actual value can be substituted (e.g., a default classification, a zero score).

4. Fail Branch​

  • The step becomes a node with two outputs:
    • Success branch — followed when the step completes normally.
    • Failure branch — followed when the step errors after retries.
  • Wire downstream logic into each branch independently — recover, log, or notify on the failure branch; continue normally on the success branch.

Use when the step's failure is a routing event, not just a value — e.g., the workflow should send a "we couldn't process" message on failure but proceed with results on success.

How retries interact with error handling​

  • If Retry is enabled, retries happen first. If any retry succeeds, the step completes normally.
  • If retries are exhausted (or retries are disabled), the Error Handling mode kicks in.
  • Each retry of the same step is tracked as a separate trace, all under the same job — visible in Live tracing and Run history.

Observability and error handling​

When Fallback Value or Continue with Error is in effect:

  • The original retry attempts appear in the trace with status FAIL.
  • A subsequent trace appears with status COMPLETED, carrying either the fallback values or the error message wrapped into the result.

This means in the trace view, you'll see both the failures (so you can debug) and the synthetic success (so you can see what flowed downstream). The job status itself is recorded as EXCEPTION to indicate that fallback was used — distinct from a pure success.

Voice agents and Sync mode​

For voice agents and Sync-mode tools, the same error handling configuration applies. Be conscious of the retry delay — too long a delay × too many retries can push a Sync step past the voice latency budget. For high-criticality voice tools, prefer Fail Branch with a fast fallback path over multiple slow retries.

  • External APIs you don't control — 3 retries with 500ms delay + Fallback Value with a sensible default.
  • LLM calls — 2 retries with 1000ms delay + Continue with Error (a downstream LLM can handle missing context).
  • Critical-path validation — no retries + Stop Workflow (you want to know immediately).
  • Side effects (writes, notifications) — 5 retries with 1000ms delay + Fail Branch (with a logging path on failure).