X Ads Troubleshooting & Debugging

Symptom Library

• X Pixel (Universal Website Tag) not loading: twq function undefined or no requests to analytics.twitter.com
• Conversion events showing zero in Events Manager despite confirmed site activity
• Tailored Audience list uploads failing with INVALID_FORMAT or TOO_FEW_RECORDS errors
• Event parameters missing from the Events Manager detail view
• Conversions API returning 400, 401, or 403 errors
• Brand safety category exclusions blocking delivery on expected inventory

Debugging with X Pixel Helper

Install the X Pixel Helper Chrome extension for real-time validation. Navigate to your site and click the extension icon to verify:

• Pixel ID matches your account (format: o1abc)
• Event type is correct (PageView, Purchase, Download, etc.)
• Event ID is present (required for Conversions API deduplication)
• Value and currency are set for revenue events

If the extension shows no events, check Console for twq is not defined (base tag failed to load).

Universal Website Tag Debugging

The X pixel sends requests to analytics.twitter.com. In the Network tab, filter for analytics.twitter.com and confirm:

// Base tag (fires on every page)
twq('config', 'o1abc');

// Conversion event with advanced matching
twq('event', 'tw-o1abc-PURCHASE', {
  value: 49.99, currency: 'USD',
  email_address: 'sha256_hashed_email',
  conversion_id: 'ORD-12345',
  event_id: 'evt-unique-id' // Required for API deduplication
});

Verify the response is 200 (a 403 indicates domain restrictions) and that twclid is preserved in landing page URLs.

Conversion Event Mapping

X event IDs follow the format tw-[PIXEL_ID]-[EVENT_TYPE]. Common suffixes: PAGE_VIEW, PURCHASE, SIGN_UP, ADD_TO_CART, DOWNLOAD. The suffix must match exactly what is configured in Events Manager -- a mismatch silently drops the event.

API v2 Error Codes for Ads

The X Ads API v2 returns structured error responses:

For Conversions API, a 422 with DUPLICATE_EVENT means your event_id was already processed -- expected when deduplication works correctly.

Tailored Audience List Upload Issues

Common failures when uploading Tailored Audiences via CSV or API:

• Minimum list size: X requires at least 100 matched users for an audience to become active.
• File format: CSV with one identifier per row (email, phone_number, twitter_id, or device_id).
• Hashing: Emails and phone numbers must be SHA-256 hashed (lowercase email first). Plaintext values are rejected with INVALID_FORMAT.
• Match rates: Typical 30-50%. Processing takes 24-48 hours.

Brand Safety Category Exclusions

Over-exclusion is the most common cause of unexpectedly low delivery on X:

• Excluding "Politics," "News," and "Controversial" reduces available inventory by 60-70%.
• Remove one exclusion category at a time to identify delivery bottlenecks.
• Third-party tools (DoubleVerify, IAS) compound with X-native exclusions.

Escalation & Communication

• X Ads Support via Ads Manager: include your account ID, pixel ID, and event IDs affected.
• X Developer Portal for API issues: include the full request/response pair.

Preventive Maintenance

• Weekly pixel health check: run X Pixel Helper on conversion pages after site deployments.
• Monthly Events Manager audit: verify all events are receiving data.
• Quarterly Tailored Audience refresh to maintain match rates.