Error Handling

Understand workflow invoke errors, control step failure behavior, and debug failed runs with workflow logs and traces

Use workflow error handling docs when a workflow request fails, a step behaves unexpectedly, or an async callback does not complete the way you expect. The goal is to separate request validation problems from workflow runtime failures so you know where to look next.

Overview

Workflow failures happen at two different layers. The first layer is request validation on the public invoke route. The second layer is workflow execution after the run starts.

For execution failures, the most useful debugging surface is Logs, where you can inspect the run detail sheet, trace waterfall, output, and webhook delivery attempts.

How do I handle workflow invoke request errors?

Start with the response body from POST /v1/workflow/invoke.

The current public route explicitly returns validation errors when required invoke fields are missing or invalid.

Examples:

{
  "error": "Missing required field: deployment or variant"
}

{
  "error": "callback_url is required when async is enabled"
}

{
  "error": "callback_url must be a valid URL"
}

Fix these request-level problems first before you inspect the workflow itself.

How do I control what happens when a workflow step fails?

Open the workflow in the editor.

Click a step to open Step settings.

For step types that expose the setting, use When the step fails to choose whether the workflow should stop or continue after that step fails.

Use Terminate Workflow when the workflow should stop immediately on that failure.

Use Continue when a failed step should not block the rest of the workflow.

This setting affects runtime behavior, so test the workflow again after you change it.

How do I debug a failed workflow run?

Open Logs.

Find the failed run in the table, then open it.

Use the trace waterfall to identify where the failure happened. Check the selected span details, request details, start inputs, metadata, and output sections as you move through the run.

If the workflow used async delivery, also inspect Webhook Logs for retry count, response code, payload, and response body.

This is the best way to separate a step failure from a delivery problem.

What runtime failure states should I expect?

The current public workflow route can surface terminal failure states such as:

• failed

• cancelled

It can also return a timeout failure if the synchronous route waits too long for the workflow to finish.

For example:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "failed",
  "error": "Workflow timed out"
}

Or:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "cancelled",
  "error": "Workflow run was cancelled"
}

Treat these as runtime failures, not request-format problems.

Error handling notes

If the invoke request succeeds but the workflow later fails, go to workflow logs rather than changing the request payload first.

If the invoke request itself returns an error object immediately, fix that request before you spend time debugging the workflow editor.

See also: Run with API, Async and Webhooks, and Logs