Flows

Handling batch failures

When Records fail in a batch, inspect the results, fix the Flow or Records, and run the batch again.

Identify failures

A batch runs a Flow once for each Record of the selected type. For batch setup and monitoring, see Running flows in batch.

To find a failed Record, open the batch results and follow these steps:

  1. Open the batch results for your run.
  2. Review the status badge and error preview for each Record row.
  3. On a failed row, click View Details.

The detail panel shows the Record metadata, output, per-step results, and error for that execution. A Record that finishes with failed steps appears as Completed with errors with a failed-step count.

Common failure types

The batch results include the error reported by the failing step or provider. Use the following table to choose a fix.

Failure typeCauseFix
Input validationA Record omits a field or value that a Flow step requires.Check the Record metadata. Ensure 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 limitConcurrent requests exceed an external API or model provider’s limit.Split the work into smaller batches. Configure Use fallbacks on prompt steps and add a Different model fallback. Ask the provider to increase your limit.
TimeoutA Record execution exceeds a batch, Flow, or step timeout.Use faster models or shorter prompts on slow steps. Configure a fallback for slow model calls.
Invalid dataRecord 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.

Rerun a batch after a fix

The dashboard does not provide a separate control to retry only failed Records. A batch retries a Record execution that throws before it marks the row as failed, but it does not retry a Record whose Flow completes with failed steps.

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.

Handle failures inside a Flow

Return a structured result from a Run Code step instead of throwing on invalid input. In this example, raw_data contains JSON text from an earlier step:

1try {
2  const parsed = JSON.parse(raw_data)
3  return { success: true, data: parsed }
4} catch (error) {
5  return { success: false, error: error.message }
6}

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. Open View Details for that row in the batch results.
  2. Review the Record metadata, output, per-step results, and error.
  3. Open Logs and select the execution to inspect its timeline and step details.

For filtering and inspecting execution history, see 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: