TikTok Ads Troubleshooting
Error Catalog
| Code | Category | Retry | Solution |
|---|---|---|---|
20001 | throttle | Yes | Rate limit — wait for x-ratelimit-reset |
20002 | throttle | Yes | Daily quota — reduce volume / wait a day |
20003 | throttle | Yes | Concurrent limit — reduce parallelism |
http-429 | throttle | Yes | A genuine HTTP 429 (not a body code) |
tiktok_api_error | payload | No | code != 0 in the JSON with HTTP 200 — check message |
transport-5xx | transport | Yes | Automatic retry |
transport-ECONNABORTED | transport | Yes | Automatic retry |
transport-ECONNRESET | transport | Yes | Automatic retry |
transport-ETIMEDOUT | transport | Yes | Automatic retry |
transport-EAI_AGAIN | transport | Yes | DNS — retry |
TikTok often responds with HTTP 200 and an error in the body (code != 0). Throttle codes: 20001, 20002, 20003.
Rate Limit
Check x-ratelimit-remaining (countdown) and x-ratelimit-reset (seconds until the window resets). Backoff: 60s → max 15min.
Authorization
The refresh token is refreshed automatically. If access to an advertiser is denied — you need a role of at least Analyst in TikTok Ads Manager.
Data
The API delay for "today" is 1–3 hours. Conversions require the Pixel / Events API.