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

# TikTok Ads Troubleshooting

> Complete troubleshooting guide for TikTok Ads integration

<Info>**Last updated:** August 14, 2025</Info>

Having trouble with your TikTok Ads integration? This guide will help you diagnose and resolve the most common issues.

## TikTok Server Instability

### Understanding TikTok's API Limitations

<Warning>
  **Error message:** "⚠️ TikTok servers are experiencing high load"
</Warning>

TikTok's API can become unstable when processing certain types of data requests, particularly:

**Large Data Requests:**

* **Ad-level data** with extensive timeframes
* **Hourly or daily aggregations** over long periods
* **Multiple accounts** with detailed breakdowns

### Quick Solutions

When you encounter this error, try these solutions in order:

<Steps>
  <Step title="Reduce Timeframe">
    **Start with a smaller date range:**

    * Instead of 6 months, try 1 month
    * For hourly data, limit to 7 days
    * For daily data, limit to 30 days
  </Step>

  <Step title="Switch to Campaign Level">
    **Use higher-level aggregations:**

    * Campaign level instead of Ad level
    * Ad Group level instead of Ad level
    * This significantly reduces API load
  </Step>

  <Step title="Change Time Aggregation">
    **Adjust your time grouping:**

    * Switch from "Hourly" to "Daily"
    * Switch from "Daily" to "All Time"
    * Use "Weekly" or "Monthly" for long timeframes
  </Step>

  <Step title="Split Your Query">
    **For large datasets, create multiple queries:**

    * Split by date ranges (e.g., monthly queries)
    * Split by account (one account per query)
    * Combine results afterward in your spreadsheet
  </Step>
</Steps>

<Info>
  **Still having issues?** If none of these solutions work, please try again in a few hours. These server instability issues typically last from a few hours to 24-48 hours in the most extreme cases.
</Info>

### Why This Happens

TikTok's API has several limitations that can trigger this error:

| Factor                        | Impact                                                                                | Solution                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Random TikTok instability** | TikTok's servers occasionally fail to process requests regardless of query complexity | Wait and retry in a few hours                                                |
| **Ad-level complexity**       | Each ad requires multiple API calls                                                   | Use Campaign or Ad Group level                                               |
| **Long timeframes**           | Exponentially more data to process                                                    | Limit to 30-90 days                                                          |
| **Granular time aggregation** | Hourly/daily creates more data points                                                 | Use weekly/monthly for long periods                                          |
| **Multiple breakdowns**       | Each dimension multiplies data volume                                                 | Reduce dimensions temporarily (e.g., age, gender, country, platform, device) |

### Best Practices to Avoid This Error

To avoid encountering this instability, we recommend implementing a **Historical + Dynamic sheet strategy**:

#### The 3-Sheet Strategy

Set up three sheets to separate your data:

1. **"TikTok Ads Combined"** - Your main reporting sheet with all data
2. **"TikTok Ads Dynamic"** - Recent data that updates daily
3. **"TikTok Ads Historical"** - Archived data that doesn't change

#### How to Implement This Strategy

<Steps>
  <Step title="Create Your Historical Sheet">
    Export all your historical data (e.g., all 2024 data and 2025 data up to the previous month) to the "TikTok Ads Historical" sheet. This data is "golden" - it won't change because TikTok's attribution windows are typically shorter.
  </Step>

  <Step title="Set Up Your Dynamic Query">
    Create a smaller query in "TikTok Ads Dynamic" that only pulls recent data (from
    the previous month onwards). This smaller timeframe rarely triggers TikTok's
    instability errors.
  </Step>

  <Step title="Combine Both Sheets">
    In your "TikTok Ads Combined" sheet, use this formula to merge both datasets:

    ```
    =QUERY({
      'TikTok Ads Historical'!A2:Z;
      'TikTok Ads Dynamic'!A2:Z
    }, "SELECT * WHERE Col1 is not null", 0)
    ```

    This gives you complete data without the load issues.
  </Step>

  <Step title="Maintain Your Setup">
    Every 6 months, or when you notice instability errors becoming more frequent, move older data from Dynamic to Historical. This keeps your dynamic query small and fast.
  </Step>
</Steps>

<Tip>
  **Example:** If you have a 2-year ad-level daily query that fails:

  * Historical sheet: All data up to June 2025
  * Dynamic sheet: July 2025 onwards
  * Combined sheet: Merges both for complete reporting

  When you encounter issues again in 1-2 years, simply repeat this optimization process.
</Tip>

<Tip>
  **Need help implementing the 3-sheet strategy?** Our support team can guide
  you through the setup process and help optimize your TikTok Ads queries for
  maximum stability. Reach out to [support@detrics.io](mailto:support@detrics.io) with your specific use case
  and we'll provide personalized recommendations.
</Tip>

## Common Issues & Solutions

<AccordionGroup>
  <Accordion title="Connection Issues">
    **Problem**: Can't connect TikTok Ads account
    **Solutions**:

    * Ensure you have admin access to the TikTok Ads account
    * Check if your TikTok Ads account is active and not suspended
    * Try disconnecting and reconnecting your account
  </Accordion>

  <Accordion title="Missing Data">
    **Problem**: Some metrics or dimensions are missing
    **Solutions**:

    * Verify your account has the necessary permissions
    * Check if the data exists in TikTok Ads Manager first
    * Some metrics may not be available for certain time periods
  </Accordion>

  <Accordion title="Rate Limits">
    **Problem**: Getting rate limit errors
    **Solutions**:

    * Reduce the frequency of your scheduled queries
    * Split large queries into smaller ones
    * Wait a few minutes between manual query executions
  </Accordion>

  <Accordion title="Timeframe Limitations">
    **Problem**: Can't pull data for certain date ranges
    **Solutions**:

    * TikTok has a 30-day limit for daily aggregation
    * Hourly data is limited to 1 day
    * Use "All Time" aggregation for longer periods
  </Accordion>
</AccordionGroup>

<Tip>
  **Need help?** If errors persist after following these steps, please reach out
  to [support@detrics.io](mailto:support@detrics.io)
</Tip>