Postback Debugging - DATALYR Documentation

Conversions tracked in DATALYR but not reaching ad platforms? This guide helps debug postback failures.

Understanding Postbacks

Postback Flow:

User converts (purchase, signup, etc.)
DATALYR receives conversion event
Conversion Rule processes event
Postback sent to ad platform (Meta, Google, TikTok)
Platform receives and attributes conversion

Any failure in steps 3-5 prevents conversion from reaching platform.

Check Postback Status

View Postback Details:

Go to Dashboard → Event Stream
Find conversion event
Click to expand details
Scroll to “Postbacks” section

Postback Statuses:

Queued: Waiting to send
Sent: Successfully delivered
Failed: Platform rejected (see error)
Skipped: Not sent (deduplication or rule condition)
Retrying: Failed, will retry automatically

Common Postback Errors

”Invalid Access Token”

Error Message:

Error: Invalid OAuth 2.0 Access Token
Code: 190 (Meta) / 401 (Google/TikTok)

Cause: OAuth connection expired or revoked. Fix:

Go to Integrations → [Platform]
Click “Reconnect”
Authorize DATALYR
Retry failed postbacks (automatic after reconnect)

“Conversion Action Not Found”

Error Message:

Error: The conversion action specified was not found
Platform: Google Ads

Cause: Conversion action name in Conversion Rule doesn’t match Google Ads. Fix:

Google Ads → Tools → Conversions
Copy exact conversion action name
DATALYR → Integrations → Conversion Rules
Edit rule → Update conversion action name
Save

”Missing Required Field”

Error Message:

Error: Missing required parameter: value
Error: Missing required parameter: currency

Cause: Event missing required fields for ad platform. Required Fields:

All Platforms: value or revenue
All Platforms: currency (e.g., USD)
Meta: event_name
TikTok: contents array (for e-commerce)

Fix: Ensure event includes all required fields:

datalyr.track('purchase', {
  revenue: 99.99,      // Required
  currency: 'USD',      // Required
  order_id: 'order_123' // Recommended
});

Update Conversion Rule:

Integrations → Conversion Rules
Edit rule
Map “Value Field” to correct property (revenue, value, amount)
Verify “Currency Field” mapped
Save

”Duplicate Event”

Error Message:

Error: Event already recorded
Reason: Duplicate event_id

Cause: Same event sent multiple times within deduplication window. Why It Happens:

Webhook fired multiple times
Client and server both tracking same conversion
Page reload after purchase

Fix: This is correct behavior (prevents double-counting). No action needed. Adjust Deduplication (if needed):

Integrations → Conversion Rules
Edit rule → Deduplication
Adjust window or disable (not recommended)

“Event Outside Attribution Window”

Error Message:

Error: Conversion not attributed
Reason: Click occurred more than 28 days ago

Cause: Conversion happened outside platform’s attribution window. Attribution Windows:

Meta: 7-day click, 1-day view
Google: 90-day click, 1-day view
TikTok: 28-day click, 1-day view

Fix: Can’t retroactively attribute. Understand attribution windows when analyzing performance.

”Missing User Data”

Error Message:

Error: Enhanced conversions require user identifier
Platform: Google Ads

Cause: Google Enhanced Conversions requires email or phone. Fix: Include email/phone in event:

datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  email: '[email protected]'  // SHA-256 hashed automatically
});

Or identify user:

datalyr.identify('user_123', {
  email: '[email protected]'
});

“Rate Limit Exceeded”

Error Message:

Error: Rate limit exceeded
Retry after: 3600 seconds

Cause: Too many requests sent to platform API. Rate Limits:

Meta: 200 requests/hour
Google: 2,000 requests/day
TikTok: 1,000 requests/hour

Fix: DATALYR automatically retries with backoff. If persistent:

Reduce number of conversion events
Contact [email protected] to optimize

”Pixel Not Found”

Error Message:

Error: Pixel ID abc123 not found
Platform: Meta / TikTok

Cause: Pixel ID in Conversion Rule doesn’t exist or no access. Fix: Meta:

Meta Events Manager → Data Sources
Copy pixel ID
DATALYR → Integrations → Meta → Update pixel ID

TikTok:

TikTok Ads Manager → Assets → Events
Copy pixel code
DATALYR → Integrations → TikTok → Update pixel code

”Test Event ID Not Found”

Error Message:

Error: Test event code invalid
Platform: Meta

Cause: Test mode enabled but test event code incorrect. Fix:

Meta Events Manager → Test Events
Generate new test event code
DATALYR → Conversion Rules → Enter test code
Or disable test mode if not testing

Platform-Specific Debugging

Meta (Facebook/Instagram)

Check Events Manager:

Meta Events Manager
Select pixel
Go to “Diagnostics” tab
Look for recent events

Event Quality Score:

Green: Good quality
Yellow: Some issues
Red: Poor quality

Improve Quality: Include customer information:

datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  email: '[email protected]',
  phone: '+1234567890',
  first_name: 'John',
  last_name: 'Doe',
  city: 'New York',
  state: 'NY',
  zip: '10001',
  country: 'US'
});

Deduplication: Meta automatically deduplicates between pixel and CAPI using event_id. DATALYR uses consistent event IDs, so deduplication works automatically.

Google Ads

Check Conversion Tracking:

Google Ads → Tools → Conversions
Select conversion action
Click “All conversions” column
Recent conversions should appear (may take hours)

Enhanced Conversions Status:

Conversions → Select action
Look for “Enhanced conversions” status
Should show “Enabled” and receiving data

Common Issues: “Conversion tracking not set up”: Enable conversion tracking in Google Ads first. “No conversions in last 7 days”: Check if conversions actually sent (Event Stream postback status). “Enhanced conversions not receiving data”: Missing email/phone in events. Add customer data.

TikTok Ads

Check Events Manager:

TikTok Events Manager
Select pixel
Go to “Events” tab
Recent events should appear

Test Events:

Events Manager → Test Events
Enable test mode in DATALYR
Send test conversion
Verify appears in test events

Contents Array: TikTok requires product data for e-commerce:

datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  contents: [
    {
      content_id: 'prod_123',
      content_name: 'Product Name',
      quantity: 1,
      price: 99.99
    }
  ]
});

Debugging Tools

Event Stream Details

View Full Event Data:

Event Stream → Click event
“Event Data” section shows all properties
“Postbacks” section shows delivery status per platform

Check:

All required fields present?
Values correct (number, not string)?
Currency code valid (USD, EUR, etc.)?

Conversion Rule Test

Test Rule Without Sending:

Integrations → Conversion Rules
Edit rule
Enable “Test Mode”
Send test event
Check Event Stream postback status
Verify correct data sent
Disable test mode

Platform Event Debugging

Meta: Use Meta Test Events to verify events received correctly. Google: Check Google Ads Conversion Tracking status page. TikTok: Use TikTok Test Events to verify events.

Automatic Retries

How Retries Work:

Failed postbacks automatically retry
Exponential backoff (1min, 5min, 15min, 1hr, 6hr)
Max 5 retry attempts
Success stops retries

Retry Reasons:

Temporary platform API errors (5xx)
Rate limit exceeded
Network timeout

Won’t Retry:

Invalid access token (4xx)
Missing required fields
Duplicate events

Check Retry Status: Event Stream → Event details → Postbacks section shows retry attempts.

Postback Payload

View Exact Data Sent: Event Stream shows summary. To see full payload:

Contact [email protected]
Provide event ID and timestamp
Support can retrieve full postback payload for debugging

Typical Payload Structure: Meta CAPI:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1672531200,
    "event_id": "evt_abc123",
    "action_source": "website",
    "user_data": {
      "em": "hash...",
      "ph": "hash...",
      "client_ip_address": "1.2.3.4",
      "client_user_agent": "Mozilla/..."
    },
    "custom_data": {
      "value": 99.99,
      "currency": "USD",
      "content_ids": ["prod_123"]
    }
  }]
}

Google Enhanced Conversions:

{
  "conversion": {
    "gclid": "abc123xyz",
    "conversion_action": "customers/123/conversionActions/456",
    "conversion_date_time": "2023-01-01 10:00:00",
    "conversion_value": 99.99,
    "currency_code": "USD",
    "user_identifiers": [{
      "hashed_email": "hash..."
    }]
  }
}

Bulk Retry Failed Postbacks

Can’t Manually Retry: DATALYR automatically retries failed postbacks. If All Retries Exhausted: Event marked as “Failed” permanently. Fix Issue Then:

Fix root cause (reconnect integration, update rule, etc.)
Future events will send correctly
Past failed events cannot be resent

Workaround for Critical Conversions: Manually upload to platform:

Meta: Events Manager → Upload offline events
Google: Conversions → Import conversions
TikTok: Events Manager → Upload events

Monitoring Postback Health

Check Postback Success Rate:

Dashboard → Overview
Look at conversion delivery metrics
Success rate should be >95%

Low Success Rate?

Check Event Stream for common errors
Review integration connection status
Verify conversion rules configured correctly

Set Up Alerts: Contact [email protected] to enable alerts for:

Postback failures above threshold
Integration disconnections
Critical conversion events failing

Best Practices

Prevent Postback Failures: 1. Include All Required Fields: Always send value, currency, and any platform-specific required fields. 2. Test Before Launch: Use test mode to verify postbacks working before going live. 3. Monitor Integration Health: Check integration status weekly, reconnect if expired. 4. Use Deduplication: Keep deduplication enabled to prevent double-counting. 5. Include Customer Data: Email/phone improves match rates and attribution quality.

Still Having Issues?

Debug Checklist:

Postback status shows “Failed” in Event Stream?
What’s the error message?
Integration connected?
Conversion Rule enabled?
Event has all required fields?
Test mode disabled (if not testing)?

Contact Support: Email [email protected] with:

Event ID from Event Stream
Screenshot of postback error
Conversion Rule settings
Integration connection status
Platform (Meta, Google, TikTok)

Next Steps

Missing Conversions

Why conversions not tracked

Integration Errors

Fix integration issues

Conversion Rules

Configure conversion rules

Event Stream

View event details

Introduction

Getting Started

Installation

Container & Tag Management

Understanding Your Data

Integrations

Features

Account & Billing

SDKs & Developer Tools

Troubleshooting

​Understanding Postbacks

​Check Postback Status

​Common Postback Errors

​”Invalid Access Token”

​“Conversion Action Not Found”

​”Missing Required Field”

​”Duplicate Event”

​“Event Outside Attribution Window”

​”Missing User Data”

​“Rate Limit Exceeded”

​”Pixel Not Found”

​”Test Event ID Not Found”

​Platform-Specific Debugging

​Meta (Facebook/Instagram)

​Google Ads

​TikTok Ads

​Debugging Tools

​Event Stream Details

​Conversion Rule Test

​Platform Event Debugging

​Automatic Retries

​Postback Payload

​Bulk Retry Failed Postbacks

​Monitoring Postback Health

​Best Practices

​Still Having Issues?

​Next Steps

Missing Conversions

Integration Errors

Conversion Rules

Event Stream

Understanding Postbacks

Check Postback Status

Common Postback Errors

”Invalid Access Token”

“Conversion Action Not Found”

”Missing Required Field”

”Duplicate Event”

“Event Outside Attribution Window”

”Missing User Data”

“Rate Limit Exceeded”

”Pixel Not Found”

”Test Event ID Not Found”

Platform-Specific Debugging

Meta (Facebook/Instagram)

Google Ads

TikTok Ads

Debugging Tools

Event Stream Details

Conversion Rule Test

Platform Event Debugging

Automatic Retries

Postback Payload

Bulk Retry Failed Postbacks

Monitoring Postback Health

Best Practices

Still Having Issues?

Next Steps