> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 callback delivery 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](./logs), where you can inspect the run detail sheet, trace waterfall, output, and callback delivery attempts.

## How do I handle workflow invoke request errors? <a href="#handle-invoke-errors" id="handle-invoke-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:

```json theme={null}
{
  "error": "Missing required field: deployment or variant"
}
```

```json theme={null}
{
  "error": "callback_url is required when async is enabled"
}
```

```json theme={null}
{
  "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? <a href="#control-step-failure" id="control-step-failure" />

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.

Sub-workflow steps follow the same rule. If the child workflow fails, the Sub-workflow step is marked failed. **Terminate Workflow** stops the parent workflow, while **Continue** records the failure and lets the parent workflow keep running.

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

## How do I debug a failed workflow run? <a href="#debug-failed-run" id="debug-failed-run" />

Open [Logs](./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 callback 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? <a href="#runtime-failure-states" id="runtime-failure-states" />

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

* `failed`
* `cancelled`

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

For example:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "failed",
  "error": "Workflow timed out"
}
```

Or:

```json theme={null}
{
  "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](./run-with-api), [Callback Delivery and Webhook Triggers](./async-and-webhooks), and [Logs](./logs)