Common Issues

Connection issues

Sign-in popup doesn't appear or is blocked

Your browser may be blocking popups from TikTok. Check your browser's popup blocker settings and allow popups for accounts.tiktok.com. Alternatively, try a different browser or incognito/private window.

"Invalid credentials" or "Authorization failed" error

Your TikTok account credentials are correct, but Coupler.io doesn't have permission to access your ad account. Verify:

1. You signed in with the correct TikTok account (the one that owns your ad accounts)

2. Your account has admin or operator role in TikTok Ads Manager

3. Two-factor authentication (2FA) is not preventing the connection

If you're still blocked, disconnect and reconnect your TikTok account in the 'Connections' section.

"Missing permissions or access rights" error

Your TikTok account doesn't have the required permissions to create API connections. Contact your TikTok account administrator and request:

• Admin or Operator role in TikTok Ads Manager

• Permission to access the Ads Manager API

Once permissions are granted, disconnect and reconnect your TikTok account.

Missing data

No data appears after connecting my TikTok account

Check these common reasons:

1. Empty ad account: Your selected ad account may have no campaigns, ads, or data in the selected date range. Verify campaigns are active in TikTok Ads Manager.

2. Wrong ad account selected: You may have selected a different account than the one with active campaigns. Verify the advertiser name matches your expected account.

3. Date range: If you selected "Campaigns" or "Ads" report type (snapshot reports), the date range is ignored. These reports show current structure only, not historical data.

4. Filters applied: If you've set advanced filters, they may be excluding all data. Try removing filters or loosening criteria.

Run the data flow again and check the logs for API error messages.

Expected metrics or dimensions don't appear in the export

Some metrics are only available in specific report types or when certain dimensions are selected:

• Conversion metrics (conversions, conversion rate, cost per conversion) require an active conversion tracking pixel or app event in TikTok Ads.

• Audience breakdown metrics are only available in "Audience" report types.

• GMV metrics (revenue, ROAS, orders) are only available in "GMV Max campaign report."

• Product data (product ID, SKU) is only available in Dynamic Showcase Ads (DSA) reports.

Select the correct report type and metrics for your analysis.

Data is different from TikTok Ads Manager

Small discrepancies are normal due to timing and attribution differences:

• Data freshness: API data may lag the dashboard by 24 hours. Export yesterday's data, not today's.

• Attribution window: The API uses a 1-day click attribution window. TikTok Ads Manager may use different windows (1, 3, 7, or 30 days).

• Time zone: Verify your TikTok Ads Manager account time zone matches your export time zone.

• Filters: Advanced filters in Coupler.io may exclude data that appears in the full dashboard.

If discrepancies persist, contact TikTok support for clarification on API attribution rules.

Permission errors

"Access denied" when pulling advertiser/account data

Your TikTok account role doesn't have access to all selected ad accounts. Verify in TikTok Ads Manager that your account has admin or operator access to each advertiser you're trying to export from. If you don't see certain accounts in Coupler.io's advertiser list, those accounts may not be accessible to your role.

Data discrepancies

Campaign data seems duplicated or has inconsistent row counts

This can occur if:

1. Dimensions are creating extra rows: If you selected multiple dimensions (e.g., country code AND age), each combination creates a separate row. Verify your dimension selections in the data flow settings.

2. Time period split: If you selected "Split data by period" (hourly, daily, etc.), each time bucket is a separate row. Check your "Split data by period" setting.

3. Append with duplicate data: If you've appended data from multiple data flows, ensure you're not pulling the same date range twice.

Review your report configuration in Coupler.io and adjust dimensions or time splits as needed.

Conversion counts don't match between Coupler.io and TikTok Ads Manager

TikTok's API and dashboard may use different attribution models:

• API: 1-day click attribution window

• Dashboard: Customizable window (1, 3, 7, or 30 days)

Small variations are normal. If you need to match the dashboard exactly, check the attribution window setting in TikTok Ads Manager and compare it to your export date range.

Rate limits

"Request to TikTok API has failed" error

TikTok enforces API rate limits to prevent abuse. If you see this error:

1. Wait 15–30 minutes before retrying the data flow

2. Reduce date range: Pulling very large date ranges (e.g., 1+ years) can trigger rate limits. Try exporting 3–6 months at a time.

3. Decrease frequency: If you're running multiple data flows simultaneously, space them out (e.g., 10–15 minutes apart) to avoid hitting limits.

4. Simplify report: Removing unnecessary dimensions or metrics can reduce API query complexity.

If errors persist after waiting, contact Coupler.io support with your data flow ID.

Data flow has been disabled due to repeated API failures

If Coupler.io detects multiple consecutive API failures, it automatically disables the data flow to prevent wasted resources. Common causes:

• TikTok API outage or maintenance

• Rate limit exceeded (see above)

• Your TikTok account permissions were revoked or changed

• Selected ad account no longer exists

Check TikTok's API status page, wait 1 hour, then re-enable the data flow in Coupler.io. If the issue continues, reconnect your TikTok account.