> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Postback Debugging

> Debug conversion postback failures to ad platforms

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

## Understanding Postbacks

**Postback Flow:**

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

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

## Check Postback Status

**View Postback Details:**

1. Go to **Dashboard → Event Stream**
2. Find conversion event
3. Click to expand details
4. 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:**

1. Go to **Integrations → \[Platform]**
2. Click "Reconnect"
3. Authorize DATALYR
4. 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:**

1. Google Ads → Tools → Conversions
2. Copy exact conversion action name
3. DATALYR → Integrations → Conversion Rules
4. Edit rule → Update conversion action name
5. 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:

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

**Update Conversion Rule:**

1. Integrations → Conversion Rules
2. Edit rule
3. Map "Value Field" to correct property (`revenue`, `value`, `amount`)
4. Verify "Currency Field" mapped
5. 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):**

1. Integrations → Conversion Rules
2. Edit rule → Deduplication
3. 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:

```javascript theme={null}
datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  email: 'user@example.com'  // SHA-256 hashed automatically
});
```

**Or identify user:**

```javascript theme={null}
datalyr.identify('user_123', {
  email: 'user@example.com'
});
```

### "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:

1. Reduce number of conversion events
2. Contact [hello@datalyr.com](mailto:hello@datalyr.com) 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:**

1. Meta Events Manager → Data Sources
2. Copy pixel ID
3. DATALYR → Integrations → Meta → Update pixel ID

**TikTok:**

1. TikTok Ads Manager → Assets → Events
2. Copy pixel code
3. 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:**

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

## Platform-Specific Debugging

### Meta (Facebook/Instagram)

**Check Events Manager:**

1. [Meta Events Manager](https://business.facebook.com/events_manager)
2. Select pixel
3. Go to "Diagnostics" tab
4. Look for recent events

**Event Quality Score:**

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

**Improve Quality:**
Include customer information:

```javascript theme={null}
datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  email: 'user@example.com',
  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:**

1. Google Ads → Tools → Conversions
2. Select conversion action
3. Click "All conversions" column
4. Recent conversions should appear (may take hours)

**Enhanced Conversions Status:**

1. Conversions → Select action
2. Look for "Enhanced conversions" status
3. 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:**

1. [TikTok Events Manager](https://business.tiktok.com/events_manager)
2. Select pixel
3. Go to "Events" tab
4. Recent events should appear

**Test Events:**

1. Events Manager → Test Events
2. Enable test mode in DATALYR
3. Send test conversion
4. Verify appears in test events

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

```javascript theme={null}
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:**

1. Event Stream → Click event
2. "Event Data" section shows all properties
3. "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:**

1. Integrations → Conversion Rules
2. Edit rule
3. Enable "Test Mode"
4. Send test event
5. Check Event Stream postback status
6. Verify correct data sent
7. Disable test mode

### Platform Event Debugging

**Meta:**
Use [Meta Test Events](https://business.facebook.com/events_manager/test_events) to verify events received correctly.

**Google:**
Check [Google Ads Conversion Tracking](https://ads.google.com/aw/conversions) status page.

**TikTok:**
Use [TikTok Test Events](https://business.tiktok.com/events_manager/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:

1. Contact [hello@datalyr.com](mailto:hello@datalyr.com)
2. Provide event ID and timestamp
3. Support can retrieve full postback payload for debugging

**Typical Payload Structure:**

**Meta CAPI:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

1. Fix root cause (reconnect integration, update rule, etc.)
2. Future events will send correctly
3. 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:**

1. Dashboard → Overview
2. Look at conversion delivery metrics
3. Success rate should be >95%

**Low Success Rate?**

1. Check Event Stream for common errors
2. Review integration connection status
3. Verify conversion rules configured correctly

**Set Up Alerts:**
Contact [hello@datalyr.com](mailto:hello@datalyr.com) 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:**

1. Postback status shows "Failed" in Event Stream?
2. What's the error message?
3. Integration connected?
4. Conversion Rule enabled?
5. Event has all required fields?
6. Test mode disabled (if not testing)?

**Contact Support:**
Email [hello@datalyr.com](mailto:hello@datalyr.com) with:

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Missing Conversions" icon="chart-line" href="/troubleshooting/missing-conversions">
    Why conversions not tracked
  </Card>

  <Card title="Integration Errors" icon="plug" href="/troubleshooting/integration-errors">
    Fix integration issues
  </Card>

  <Card title="Conversion Rules" icon="arrows-turn-to-dots" href="/integrations/conversion-rules">
    Configure conversion rules
  </Card>

  <Card title="Event Stream" icon="water" href="/features/event-stream">
    View event details
  </Card>
</CardGroup>