> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Handling batch failures

When Records fail in a batch, find the failed Records, fix the Flow or the Records, and run the batch again.

## Before you begin

Run a batch on a Flow. For instructions, see [Running flows in batch](/user-guide/flows/running-flows-in-batch).

## Identify failures

Where you inspect failures depends on how the batch started.

To find failed Records in a batch that a Schedule started, follow these steps:

1. On the **Schedules** page, open the Schedule.
2. On the **Runs** tab, click the run. The batch results open.
3. In the status filter, select **Failed**.
4. Optional: To find one Record, click **Find a record** and enter its Record ID.
5. On a failed row, click the details icon (**View details**).

The detail panel shows the Record metadata, output, per-step results, and error for that execution. The results header shows how many Records finished with failed steps.

To find failed Records in a batch that you started from the Flow editor or through the API, follow these steps:

1. Open **Logs**.
2. In **Type**, select **Batch**.
3. Review the entries for failed Records. Each entry names the Record's position in the batch and its error.

A Record whose Flow finishes with failed steps does not get a failed **Batch** entry. To find these Records, select **Flow** in **Type** and review the step results of each Flow execution.

## Read the error

Each failed row shows one of the following kinds of error:

* The error that stopped the execution, such as a timeout or a provider error.
* `Flow completed with one or more failed steps`. The Flow finished, but at least one step failed and was set to continue. To see that step's error, open the row's details and check the per-step results.

## Common failure types

Use the following table to choose a fix for the error on a failed Record.

| Failure type        | Cause                                                                 | Fix                                                                                                                                                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input validation    | A Record omits a field or value that a Flow step requires.            | Check the Record metadata. Make sure that Records of this type include the required fields. Add an input validation or default-handling step near the start of the Flow.                                                                                                    |
| Provider rate limit | Concurrent requests exceed an external API or model provider's limit. | Configure **Use fallbacks** on prompt steps and add a **Different model** fallback. Through the batch API, lower `options.recordConcurrency` (default 8) or set `options.modelOverride` to a different model. In the dashboard, split the work into smaller batches.        |
| Timeout             | A Record execution exceeds the batch, Flow, or step timeout.          | Use faster models or shorter prompts on slow steps. Through the batch API, raise `options.timeoutMs`, `options.flowTimeoutMs`, or `options.stepTimeoutMs`. For defaults and limits, see [Timeouts and long-running work](/user-guide/flows/timeouts-and-long-running-work). |
| Invalid data        | Record data does not match the format that a step expects.            | Add a **Run Code** step to normalize the data. Correct the affected Records. Configure error handling for the step.                                                                                                                                                         |
| Spend cap reached   | Your workspace reached its monthly spend cap.                         | The remaining Records fail with a spend cap message, and the batch stops. Raise or clear the cap in **Billing** under **Settings**, then rerun.                                                                                                                             |
| Batch cancelled     | Someone cancelled the batch before these Records finished.            | Rerun the batch, or submit only the affected Record IDs through the batch API.                                                                                                                                                                                              |

## If the batch does not start

A batch can be rejected before any Record runs. The dashboard shows the error in a notification, and the API returns it in the response.

| Error                                            | Cause                                                                    | Fix                                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `Rate limit exceeded` (HTTP 429)                 | You submitted more than 250,000 batch Records in the current clock hour. | Wait for the next hour, or split the work over a longer period.                        |
| Daily execution limit exceeded (HTTP 429 or 402) | The batch has more Records than your remaining daily executions.         | Reduce the number of Records, wait for the daily limit to reset, or upgrade your plan. |
| `No records found for this type` (dashboard)     | The selected Record type has no Records.                                 | Create or import Records of that type on the **Records** page.                         |
| `Feature Not Available` (HTTP 402)               | Your plan does not include batch submission with an API key.             | Upgrade to Growth or higher, or run the batch from the dashboard.                      |
| Validation error (HTTP 400)                      | The request has an unknown option or an option out of range.             | Correct the option values. The API reference lists each option and its range.          |

## Check failures with the API or CLI

If you started the batch through the API, an SDK, or the CLI, use these calls to check it:

* `GET /v1/batch/status/{id}` returns the batch status, `processedRecords`, and `failedRecords`.
* `GET /v1/batch/{batchId}/records/{recordId}/steps` returns the step results for one Record, ordered as a timeline.
* `runtype batch status BATCH_ID --watch` polls the batch until it finishes, or until the watch timeout (5 minutes by default) passes. Replace `BATCH_ID` with the batch execution ID.

For request and response details, see the Batch entries in the API reference.

## Stop a failing batch

If most Records are failing, cancel the batch before you fix the Flow. This stops spending on a broken run. The dashboard does not have a cancel control, so use one of these options:

* Run `runtype batch cancel BATCH_ID`.
* Call `POST /v1/batch/cancel/{id}`.

Records that did not finish fail with `Batch was cancelled`. To copy the batch ID, click the batch ID in the batch results header, or copy the **Batch** field of a batch entry in **Logs**.

## Rerun a batch after a fix

A batch retries a Record whose execution fails with an error, such as a timeout or a step set to **Stop on error**. A batch that you start from the Flow editor retries the Record up to 5 times before it marks the row **Failed**. A batch that the API or a Schedule starts retries up to 3 times by default. To change this, set `options.maxRetries` (0 to 10) when you start the batch through the API. A Record whose Flow finishes with failed steps is not retried.

To rerun the batch for the same Record type, follow these steps:

1. Fix the Flow logic or correct the affected Records on the **Records** page.
2. In the Flow editor, click **Run flow**.
3. Select the **Batch** tab.
4. Select the same **Record Type**.
5. Click **Run on Records**.

To publish the Flow change, click **Publish** after you test the batch.

The dashboard reruns every Record of the type. To rerun only the failed Records, submit their Record IDs in `recordIds` through the batch API. For details, see [Running flows in batch](/user-guide/flows/running-flows-in-batch).

## Handle failures inside a Flow

By default, a **Run Code** step continues after a script error. The step stores its default value, the Flow keeps running, and the batch marks the Record as completed. The script error appears only in the per-step results. To make a script error fail the Record, set the step to **Stop on error**. For details, see [Handle errors](/user-guide/flows/using-transform-data-steps#handle-errors).

To route invalid input yourself, return a structured result from the **Run Code** step:

```javascript
try {
  const parsed = JSON.parse(input.raw_data)
  return { success: true, data: parsed }
} catch (error) {
  return { success: false, error: error.message }
}
```

Replace `raw_data` with the output variable of the earlier step that contains the JSON text.

Use a **Conditional Logic** step to branch on the `success` field and route invalid Records to an error path. On prompt steps, select **Use fallbacks** to retry the same model, use a different model, or return a fixed message when the configured trigger fires.

## Debug an individual failure

To investigate one failed Record, follow these steps:

1. In the batch results, click the details icon (**View details**) on that row.
2. Review the Record metadata, output, per-step results, and error.
3. To see the run history for each Record, click **Record runs** in the batch results header. Alternatively, open **Logs** and select the execution to inspect its timeline and step details.

For filtering and inspecting execution history, see [Working with logs](/user-guide/logs/working-with-logs).

## Prevent failures

Use these practices before you scale a batch:

* **Validate inputs:** Add validation or default handling near the start of the Flow.
* **Handle step errors:** Use `try`/`catch` in **Run Code** steps and branch with **Conditional Logic**.
* **Configure prompt fallbacks:** Add a different model for rate limits and slow model calls.
* **Test edge cases:** Run a small batch against Records with missing or malformed data.
* **Review limits:** Check provider rate limits, your spend cap, and available credit before starting a large batch.

## Next steps

Continue with these guides:

* [Running flows in batch](/user-guide/flows/running-flows-in-batch): learn to start and monitor a batch.
* [Timeouts and long-running work](/user-guide/flows/timeouts-and-long-running-work): set batch, Flow, and step timeouts.
* [Debugging flows](/user-guide/flows/debugging-flows): inspect Flow steps and execution errors.
* [Using prompt steps](/user-guide/flows/using-prompt-steps): configure prompt error handling and fallbacks.
* [Automating batch processing](/user-guide/schedules/automating-batch-processing): schedule batches with Schedules.