Flows

Handling batch failures

When some Records in a batch fail, diagnose them from the batch results, fix the underlying flow or Records, and run the batch again.

Identifying failures

A batch runs your Flow once per Record of the chosen type (see Running flows in batch). The batch results show one row per Record:

  1. Open the batch results for your run
  2. Each Record row shows a status badge; failed rows show an inline error preview
  3. Click View Details on a failed row to drill into that Record’s execution

The detail view shows the Record metadata, the step output, and the error for that single execution, so you can see exactly which input failed and why.

Common failure types

Input validation errors

Error: Missing required field: customerId

Cause: A Record is missing a field the Flow expects.

Fix:

  • Check the Record’s metadata for the missing field
  • Ensure every Record of this type has the fields the Flow references
  • Add a validation or default-handling step at the start of the Flow

API rate limits

Error: Rate limit exceeded

Cause: Too many concurrent requests to an external API or AI model provider.

Fix:

  • Split the work into smaller batches
  • Add a model fallback chain on prompt steps so a rate-limited model fails over to another
  • Ask the provider to increase your rate limits

Timeout

Error: Execution timed out

Cause: Individual executions take too long to process.

Fix:

  • Use faster models or simpler prompts on slow steps
  • Set a model-call duration cap with a fallback on prompt steps
  • Exclude Records that consistently time out

Invalid data

Error: Invalid JSON or Type error

Cause: A Record’s data doesn’t match the format a step expects.

Fix:

  • Add a transform step to normalize the data before the step that fails
  • Correct the underlying Records
  • Guard the risky step with error handling

Re-running after a fix

There is no separate “retry failed items” control. To reprocess failures:

  1. Fix the cause — update the Flow logic, or correct the affected Records on the Records page
  2. Publish the updated Flow if you changed it
  3. Run the batch again against the same Record type

Because a batch runs over a Record type, fixing the Records and re-running is the path back to a clean result. To stop a run that is going wrong, cancel the batch while it is still processing.

Handling failures inside the Flow

Design Flows so a single bad input does not break the step. In a Run Code step, wrap risky work in try/catch and return a structured result:

1try {
2  const result = riskyOperation(input);
3  return { success: true, result };
4} catch (error) {
5  return { success: false, error: error.message };
6}

Downstream steps can then branch on success with a Conditional Logic step instead of failing the whole execution. Prompt steps have their own error-handling control (continue, stop, or fall back to another model) for model-level failures.

Debugging an individual failure

To investigate one failed Record:

  1. Open View Details for that row in the batch results
  2. Review the Record metadata, step output, and error
  3. For the full execution trace, open Logs and find the execution

See Working with logs for detailed troubleshooting.

Preventing future failures

  • Validate inputs: Add validation or defaults at the start of the Flow
  • Handle errors gracefully: Use try/catch in Run Code steps and conditionals to branch on failure
  • Use model fallbacks: Configure fallback models on prompt steps for rate limits and timeouts
  • Test with edge cases: Run a small batch against problematic Records before scaling up
  • Watch your quota: Make sure you have enough provider rate limit and execution budget for the batch size

Next steps