Error Handling

Retrieve provides robust error handling mechanisms to ensure your integrations are reliable, recoverable, and maintainable. When things go wrong (and they will), you need visibility, control, and automated recovery options.

Understanding Job Failures

In Retrieve, every integration run is a "job". Jobs can fail for various reasons:

Common Failure Scenarios

Automatic Retry Mechanism

Retrieve can automatically retry failed jobs, which is especially useful for transient errors like network issues or temporary API outages.

Configuring Retry Behavior

For each integration, you can configure:

How Retry Works

Best Practices for Retry Configuration

Email Notifications

Retrieve includes a powerful notification engine that alerts you when integrations fail, so you can take action before issues escalate.

Notification Features

Setting Up Notifications

Configure notifications in your integration settings:

1. Enable Notifications

   Turn on "Notify (if it fails)" in integration settings

2. Set Failure Threshold

   Configure how many consecutive failures trigger a notification (e.g., 3 failures)

   Threshold = 3 means:
   - 1st failure: No notification (waiting...)
   - 2nd failure: No notification (waiting...)
   - 3rd failure: ✉️ Email sent to all recipients

3. Add Recipients

   Add email addresses of people who should be notified:

   • Name: Person's name for identification
   • Email: Where to send the notification
   • Type: Admin or Customer user
   • Language: Preferred notification language

Understanding Failure Thresholds

The notification threshold prevents alert fatigue by only notifying after multiple consecutive failures:

Notification Email Content

When a notification is triggered, you receive an email containing:

• Integration Name - Which integration failed
• Failure Count - How many times it has failed consecutively
• Error Message - Detailed error description
• Timestamp - When the failure occurred
• Job ID - Link to view full job details in the dashboard
• Stack Trace - Technical details for debugging (if available)

Notification Best Practices

Job History & Logs

Every job execution is logged in the Retrieve dashboard, providing complete visibility into successes, failures, and errors.

Accessing Job History

1. Navigate to Job History in the Retrieve dashboard
2. Filter by integration, date range, or status (success/failed)
3. Click any job to view detailed execution logs

What's Logged

Error Handling in Rewrite Functions

You can implement custom error handling logic in your rewrite functions to gracefully handle issues:

Try-Catch for Error Handling

let job = jobData.job;
let sourceData = job.data.data;

try {
  // Attempt to process data
  let processedData = sourceData.map(item => {
    // Your transformation logic
    return {
      id: item.id,
      name: item.customer.name, // Could fail if customer is null
      email: item.customer.email
    };
  });
  
  return {
    jobStatus: 1, // Success
    data: processedData
  };
  
} catch (error) {
  console.error('Error processing data:', error.message);
  
  return {
    jobStatus: 0, // Failed
    data: [],
    message: `Failed to process data: ${error.message}`
  };
}

Conditional Data Processing

Skip invalid records instead of failing the entire job:

let job = jobData.job;
let orders = job.data.data;

// Filter out invalid orders instead of failing
let validOrders = orders.filter(order => {
  // Check if order has required fields
  if (!order.id || !order.customer_email) {
    console.log(`Skipping invalid order: ${JSON.stringify(order)}`);
    return false;
  }
  return true;
});

console.log(`Processing ${validOrders.length} of ${orders.length} orders`);

return {
  jobStatus: 1,
  data: validOrders,
  message: `Processed ${validOrders.length} valid orders, skipped ${orders.length - validOrders.length}`
};

Custom Error Responses

Return specific error information to help with debugging:

let job = jobData.job;

// Validate configuration
if (!job.config.api_key) {
  return {
    jobStatus: 0,
    data: [],
    message: 'Missing API key in integration configuration. Please add API key in settings.'
  };
}

// Validate data
if (!job.data.data || job.data.data.length === 0) {
  return {
    jobStatus: 1, // Success, but no data
    data: [],
    message: 'No records to process - source returned empty result'
  };
}

Common Error Patterns & Solutions

Monitoring Integration Health

Proactive monitoring helps you catch issues before they become critical:

Key Metrics to Track

Regular Health Checks

• ✅ Review job history weekly for failure patterns
• ✅ Monitor notification emails and investigate repeated failures
• ✅ Test integrations after credential updates or API changes
• ✅ Keep integration packages updated to latest versions
• ✅ Document common errors and their solutions for your team

Next Steps

• Performance Optimization - Learn how to make your integrations faster and more efficient
• Integrations - Understand integration lifecycle and best practices
• Rewrite Functions - Implement custom error handling in your code