# Error Handling

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](https://docs.fetchhive.com/workflows/logs), where you can inspect the run detail sheet, trace waterfall, output, and webhook delivery attempts.

## How do I handle workflow invoke request errors? <a href="#handle-invoke-errors" id="handle-invoke-errors"></a>

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
{
  "error": "Missing required field: deployment or variant"
}
```

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

```json
{
  "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"></a>

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? <a href="#debug-failed-run" id="debug-failed-run"></a>

Open [Logs](https://docs.fetchhive.com/workflows/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? <a href="#runtime-failure-states" id="runtime-failure-states"></a>

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:

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

Or:

```json
{
  "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](https://docs.fetchhive.com/workflows/run-with-api), [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks), and [Logs](https://docs.fetchhive.com/workflows/logs)