Skip to main content

​
Why Error Handling Matters

Things go wrong. APIs go down, data comes in unexpected formats, or services hit rate limits. The question isn’t if your workflow will encounter errors - it’s how it handles them. Good error handling means:
  • Your workflows recover gracefully instead of failing silently
  • You get notified when something needs attention
  • Critical data doesn’t get lost
  • Your team knows what went wrong and where
[IMAGE_ERROR_HANDLING_COMPARISON] 🛡️ GRAPHIC SUGGESTION: Diagram showing two workflows side-by-side: one without error handling (fails completely) vs. one with error handling (recovers or notifies).

​
Error Handling Strategies

Each node in your workflow can handle errors differently. Choose the right strategy 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
Example: 
Process Payment → [FAILS] → Workflow stops, run marked as failed

​
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
Example: 
Send Welcome Email → [FAILS] → Log error, but continue to next node
Use this sparingly. Make sure you’re actually monitoring logs, or failed steps might go unnoticed.

​
Error Callback Path

The workflow routes to a different set of 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)
Example: 
Call Primary API → [FAILS] → Try Backup API → Continue
                 → [SUCCESS] → Continue
[IMAGE_ERROR_CALLBACK_PATHS] 🔀 GRAPHIC SUGGESTION: Visual diagram showing a node with both success (green) and error (red) handles leading to different paths.

​
Configuring Error Handling

To set up error handling for a node:
  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
💡 Pro tip: You can have multiple layers of error handling. Your error callback nodes can also have their own error handlers!

​
Common Error Handling Patterns

​
The Notification Pattern

Always notify someone when critical workflows fail: 
Critical Step → [ERROR] → Send Urgent Notification → Fail Workflow
Code for notification: 
🚨 Workflow Failed:
{{workflow.name}}

Node:
{{failed_node.name}}
Error:
{{error.message}}

Run ID:
{{run.id}}
Time:
{{run.timestamp}}

​
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 → [ERROR] → Manual Fallback
                → [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

# Validate required fields
required_fields = ['email', 'name', 'amount']

for field in required_fields:
    if not trigger.get(field):
        raise ValueError(f"Missing required field: {field}")

# Validate data types
if not isinstance(trigger.get('amount'), (int, float)):
    raise ValueError("Amount must be a number")

# Validate ranges
if trigger.get('amount', 0) < 0:
    raise ValueError("Amount cannot be negative")

# If all valid, return the data
return trigger

​
Using a Condition Node

Trigger → Condition (Check if email exists) → [YES] → Continue
                                            → [NO] → Send error notification
[IMAGE_VALIDATION_PATTERNS] 📋 GRAPHIC SUGGESTION: Flowchart showing validation patterns at the start of workflows, with success and failure paths clearly marked.

​
Handling External API Errors

APIs can fail in different ways. Here’s how to handle common scenarios:

​
Rate Limiting

When an API responds with a rate limit error: 
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

When a workflow fails, here’s how to investigate:

​
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 will highlight 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. Check the Error Details

Common error types and what they mean:
  • Validation Error: Input data didn’t match expected format
  • Connection Error: Couldn’t reach the API or service
  • Timeout Error: Operation took too long
  • Authentication Error: Invalid credentials or expired token
  • Rate Limit Error: Too 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
[IMAGE_FAILED_RUN_DEBUG_VIEW] 🔍 GRAPHIC SUGGESTION: Screenshot of the Runs tab showing a failed execution with the failed node highlighted and the error details panel visible.

​
Error Monitoring Best Practices

​
Set Up Alerts

Configure notifications for critical workflow failures:
  1. Go to workflow settings
  2. Add notification recipients
  3. Choose notification conditions (all failures, or just critical ones)

​
Review Error Logs Regularly

Check your workflow runs weekly:
  • Are certain nodes failing often?
  • Are errors happening at specific times?
  • Do errors correlate with external events?

​
Document Known Issues

Add comments to nodes that have known quirks: 
"Note: This API sometimes returns 500 errors during deployments
(usually Wednesdays around 2 AM). These resolve within 10 minutes."

​
Create Error Dashboards

For production workflows, track:
  • Success rate over time
  • Most common error types
  • Average recovery time
  • Cost of failed runs

​
Preventing Common Errors

​
Use Structured Outputs

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

​
Validate Variables Exist

Before using a variable, check it exists: 
# Good
customer_name = trigger.get('name', 'Unknown Customer')

# Risky
customer_name = trigger['name']  # Fails if 'name' doesn't exist

​
Handle Empty Arrays

Check array length before looping: 
items = trigger.get('items', [])

if len(items) == 0:
    return {"message": "No items to process"}

# Process items...

​
Set Timeouts

Always set reasonable timeouts for external calls:
  • HTTP requests: 30 seconds
  • AI agent calls: 60 seconds
  • Complex computations: Based on expected duration + buffer

​
Testing Error Scenarios

Don’t just test the happy path - test failure scenarios too:

​
What to Test

  • Missing required fields in forms
  • Invalid data formats (wrong types, bad emails, etc.)
  • Empty arrays or null values
  • API failures (use a test endpoint that returns errors)
  • Rate limiting scenarios
  • Large data volumes

​
How to Test

  1. Create a test run with intentionally bad data
  2. Verify your error handlers activate
  3. Check that notifications are sent
  4. Ensure no data is corrupted
[IMAGE_ERROR_TESTING_CHECKLIST] 🧪 GRAPHIC SUGGESTION: Checklist or diagram showing different error scenarios to test before going to production.

​
When to Let It Fail

Not every error needs handling. Sometimes failing fast is the right choice:
  • Data corruption: 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
The key is being intentional about which errors you handle and which you don’t.

​
Next Steps

Best Practices

More patterns for reliable workflows

Cost Management

Control and optimize workflow costs

Core Concepts

Learn workflow fundamentals

Getting Started

Build your first workflow