Error Handling

Sync errors are inevitable when working with multiple systems. This guide covers common error types, how to diagnose them, and strategies for resolution.

Error Categories

Connection Errors

Problems connecting to external systems:

Data Errors

Problems with the data being synced:

Mapping Errors

Problems with the mapping configuration:

Error Handling Strategies

Skip and Continue

The default behavior – skip the failed record and continue with others:

• Other records still sync successfully
• Failed records logged for review
• Good for non-critical errors

Configure: This is the default behavior.

Retry with Backoff

Automatically retry failed operations:

Attempt 1: Immediate
Attempt 2: Wait 1 minute
Attempt 3: Wait 5 minutes
Attempt 4: Wait 30 minutes
Attempt 5: Mark as failed

Configure: Enable in mapping settings under Error Handling.

Fail Fast

Stop the entire sync on first error:

• Use for critical data integrity
• Prevents partial syncs
• Requires manual intervention

Configure: Enable Stop on Error in mapping settings.

Queue for Manual Review

Flag errors for human review before retry:

• Best for complex data issues
• Allows data correction before retry
• Prevents repeated failures

Configure: Enable Manual Review Mode in settings.

Viewing Errors

Sync Details Page

1. Go to Syncs
2. Click on a sync with errors
3. View the Errors tab

Each error shows:

• Affected record
• Error message
• Field involved
• Timestamp

Error Dashboard

Navigate to Syncs → Errors for:

• All errors across mappings
• Filter by type, date, mapping
• Bulk retry options

Notifications

Configure error alerts:

1. Go to Settings → Notifications
2. Enable Sync Errors
3. Choose notification method (email, Slack, etc.)
4. Set threshold (every error, daily digest, etc.)

Common Errors and Solutions

"Invalid phone number format"

Cause: Phone number doesn't match expected format.

Example: (555) ABC-1234 or call me maybe

Solutions:

• Add phone_e164 transformation to normalize format
• Set Skip invalid option for phone field
• Fix data at source

"Email is required"

Cause: Target system requires email, source record has none.

Solutions:

• Make the field pair non-required in FluxCascade
• Add a default value transformation
• Filter records without email from sync

"Rate limit exceeded"

Cause: Too many API requests to external system.

Solutions:

• Reduce sync frequency
• Use incremental syncs instead of full
• Contact platform for higher limits

"Record not found"

Cause: Trying to update a record that was deleted.

Solutions:

• Enable Create if missing option
• Ignore delete events from source
• Check for out-of-order operations

"Duplicate key violation"

Cause: Trying to create a record that already exists.

Solutions:

• Improve matching strategy
• Enable Upsert mode (update or create)
• Check for duplicate source records

Retry Failed Syncs

Individual Record Retry

1. Open the failed sync
2. Go to Errors tab
3. Select records to retry
4. Click Retry Selected

Bulk Retry

1. Go to Syncs → Errors
2. Filter errors as needed
3. Select all or specific errors
4. Click Retry All

Automatic Retry

Enable automatic retry for transient errors:

1. Edit mapping settings
2. Enable Auto Retry
3. Set Max Retries (default: 3)
4. Set Retry Delay (default: exponential)

Preventing Errors

1. Validate Data at Source

Clean data before it enters the sync:

• Validate email formats
• Normalize phone numbers
• Remove duplicates

2. Use Appropriate Transformations

Add transforms to handle data variations:

• trim for extra whitespace
• phone_e164 for phone normalization
• lowercase for email consistency

3. Set Default Values

Provide fallbacks for missing data:

• Default country for phone formatting
• Default value for required fields
• Empty string instead of null

4. Test Before Full Sync

Use test mode:

1. Create mapping
2. Run Test Sync with small dataset
3. Review results and errors
4. Fix issues
5. Enable full sync

5. Monitor Regularly

Review sync health weekly:

• Error rates
• Common error types
• Patterns in failures

Error Metrics

Track error health over time:

• Error Rate: Percentage of records that fail
• Error Types: Breakdown by category
• Resolution Time: How quickly errors are fixed
• Retry Success: How often retries succeed

Access via Syncs → Analytics.

Next Steps

• How Syncs Work – Understanding the sync process
• Troubleshooting – General troubleshooting guide
• Contact Support – Get help with persistent errors