Skip to main content

​
Why Error Handling Matters

Things go wrong. APIs go down, data comes in unexpected formats, or services hit rate limits. Good error handling means your workflows recover gracefully, you get notified when something needs attention, and critical data doesn’t get lost.

​
Error Handling Strategies

Each node can handle errors differently. Choose based on how critical that step is.

​
Fail Workflow (Default)

The workflow stops immediately and marks the run as failed. When to use:
  • Critical steps that must succeed (payment processing, data validation)
  • Steps where continuing would cause data corruption
  • When you need immediate attention to fix the issue

​
Continue Workflow

The node logs the error but the workflow keeps going. When to use:
  • Nice-to-have features (sending a courtesy notification)
  • Non-critical integrations
  • Steps where partial success is acceptable
Use this sparingly. Make sure you’re monitoring logs, or failed steps might go unnoticed.

​
Error Callback Path

The workflow routes to different nodes when this node fails (using the red error handle). When to use:
  • Implementing fallback logic
  • Retry mechanisms
  • Error-specific handling (like trying a backup API)

​
Configuring Error Handling

  1. Click on the node to open its configuration
  2. Find the Error Handling section
  3. Choose your strategy:
    • Fail workflow (default)
    • Continue workflow
    • Route to error handler (adds red error handle)

​
Adding Error Callback Paths

When you select “Route to error handler”:
  1. A red handle appears on the right side of the node
  2. Drag from this handle to create your error path
  3. Add nodes to handle the error (notifications, fallback logic, etc.)
  4. Both success and error paths can eventually merge back together

​
Common Error Handling Patterns

​
The Notification Pattern

Always notify someone when critical workflows fail: 
Critical Step → [ERROR] → Send Notification → Fail Workflow

​
The Retry Pattern

Try an operation multiple times before giving up: 
API Call → [ERROR] → Wait 5 seconds → Retry API Call → [ERROR] → Notify & Fail
         → [SUCCESS] → Continue
Set a maximum retry count to avoid infinite loops. Use a condition node to track retry attempts.

​
The Fallback Pattern

Try a backup option when the primary fails: 
Primary Service → [ERROR] → Try Secondary Service → Continue
                → [SUCCESS] → Continue

​
The Graceful Degradation Pattern

Continue with reduced functionality: 
Enrich with API → [ERROR] → Use cached data → Continue
                → [SUCCESS] → Continue

​
Validating Data Early

Prevent errors by validating inputs at the start of your workflow:

​
In a Code Node

const requiredFields = ['email', 'name', 'amount'];

for (const field of requiredFields) {
  if (!trigger.output[field]) {
    throw new Error(`Missing required field: ${field}`);
  }
}

// Validate data types
if (typeof trigger.output.amount !== 'number') {
  throw new Error("Amount must be a number");
}

// Validate ranges
if (trigger.output.amount < 0) {
  throw new Error("Amount cannot be negative");
}

return trigger.output;

​
Using a Condition Node

Trigger → Condition (email exists?) → [YES] → Continue
                                    → [NO] → Send error notification

​
Handling External API Errors

​
Rate Limiting

API Call → [Rate Limited] → Wait 60 seconds → Retry → Continue

​
Timeouts

Set appropriate timeout values and have fallback logic: 
API Call (30s timeout) → [Timeout] → Try faster endpoint → Continue

​
Authentication Failures

Often means your credentials expired: 
API Call → [Auth Error] → Notify admin → Fail workflow
Check your integration connections regularly. Many expire after 30-90 days and need re-authorization.

​
Debugging Failed Workflows

​
1. Check the Run History

  1. Go to the Runs tab at the bottom of the canvas
  2. Find the failed run (marked in red)
  3. Click to open the execution details

​
2. Identify the Failed Node

The canvas highlights which node failed. Click on it to see:
  • Input: What data it received
  • Error message: What went wrong
  • Logs: Any console output (for code nodes)

​
3. Common Error Types

Error TypeMeaning
Validation ErrorInput data didn’t match expected format
Connection ErrorCouldn’t reach the API or service
Timeout ErrorOperation took too long
Authentication ErrorInvalid credentials or expired token
Rate Limit ErrorToo many requests to the service

​
4. Test the Fix

  1. Make your changes in the draft version
  2. Use the same input data from the failed run to test
  3. Verify the fix works before publishing

​
Preventing Common Errors

​
Use Structured Outputs

When using agent nodes, define structured output schemas. This guarantees the data format and prevents parsing errors in downstream nodes.

​
Validate Variables Exist

Use optional chaining or defaults: 
// Safe - uses default if missing
const customerName = trigger.output?.name || 'Unknown Customer';

// Safe - check before using
if (trigger.output.items?.length > 0) {
  // Process items
}

​
Handle Empty Arrays

Check array length before looping: 
const items = trigger.output.items || [];

if (items.length === 0) {
  return { message: "No items to process" };
}

// Process items...

​
Testing Error Scenarios

Don’t just test the happy path - test failure scenarios too:
  • Missing required fields in forms
  • Invalid data formats (wrong types, bad emails)
  • Empty arrays or null values
  • API failures
  • Rate limiting scenarios

​
When to Let It Fail

Not every error needs handling. Sometimes failing fast is the right choice:
  • Data corruption risk: Better to stop than process corrupt data
  • Critical validation: If the data doesn’t meet requirements, don’t continue
  • Unrecoverable errors: Some errors can’t be fixed by the workflow

​
Next Steps

Best Practices

More patterns for reliable workflows

Cost Management

Control and optimize workflow costs