频控规则
调用 API 需要遵循 API 系统本身的限制，我们对 API 所有的接口都设定了调用频次限制。本篇将为您介绍我们的频控限制。我们的频控限制分为全局限制和某些接口的请求限制。
全局频控限制指的是每一个开发者应用在单位时间内总共能够发起的请求数。
接口特定频控限制适用于特定的接口或者接口组。接口特定频控对于不同接口是独立的。例如，开发者应用A调用/campaign/get接口达到频率上限不会影响该开发者应用调用/ad/get/接口。
全局频控限制
我们针对每一个开发者应用都设置了四个不同等级的调用频次限制，每个等级包括了秒级调用限制（QPS）、分钟级调用限制（QPM）、天级调用限制（QPD）。
如果请求达到了频控上限，服务器将返回 "code": 40100 ，代表您的请求被节流。此时，您需要暂停调用一段时间后重新开始调用（暂停时间取决于触发的频控类型）。例如对于QPD，您需要第二个自然日（UTC+0 时间）才能重新发起请求。对于QPM，您需要等待5分钟。QPD频控在每日UTC+0 时间的0点会重置。
频控等级
| 等级 | QPS | QPM | QPD |
|---|---|---|---|
| 初级 | 10 | 600 | 864,000 |
| 标准级 | 20 | 1,200 | 1,728,000 |
| 高级 | 30 | 1,800 | 2,592,000 |
| 合作级 | 50 | 3,000 | 4,320,000 |
注意
* 所有应用默认等级为初级。若要变更QPS频控上限，请通过应用管理> App Detail > 授权界面进行申请。
* 每次申请只能往上增加一级API频控上限（从初级到标准级/从标准到高级/从高级到合作级）。申请时，请用英文描述增加频控上限的理由。以下示例供您参考：
The current API Rate Limit is not sufficient in the reporting use case, where we encounter errors occasionally. Therefore, we are applying for rate limit increase. * 您无需针对报告事件接口申请频控等级变更，因为各等级对应的其频控上限是相同的。
接口特定频控限制
| 接口 | 初级 | 标准级 | 高级 | 合作级 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 限制类型 | QPS | QPM | QPD | QPS | QPM | QPD | QPS | QPM | QPD | QPS | QPM | QPD |
| /creative/quick_optimization/create/ | 1 | 30 | 5,000 | 2 | 60 | 10,000 | 3 | 180 | 15,000 | 3 | 180 | 15,000 |
| /creative/smart_video/create/ | 1 | 30 | 5,000 | 2 | 60 | 10,000 | 3 | 180 | 15,000 | 3 | 180 | 15,000 |
| /ad/create/ | 5 | 150 | 86,400 | 10 | 200 | 86,400 | 10 | 300 | 86,400 | 15 | 300 | 86,400 |
| /video_template/task/create/ | 1 | 30 | 5,000 | 2 | 60 | 10,000 | 3 | 180 | 15,000 | 3 | 180 | 15,000 |
| /catalog/product/file/ | 5 |
300 | 432,000 | 5 | 300 | 432,000 | 10 | 600 | 864,000 | 10 | 600 | 864,000 |
| /catalog/product/upload/ | 5 |
300 | 432,000 | 5 | 300 | 432,000 | 10 | 600 | 864,000 | 10 | 600 | 864,000 |
| /catalog/product/update/ | 2 | 120 | 172,800 | 2 | 120 | 172,800 | 5 | 300 | 432,000 | 5 | 300 | 432,000 |
| /catalog/product/delete/ | 2 | 120 | 172,800 | 2 | 120 | 172,800 | 5 | 300 | 432,000 | 5 | 300 | 432,000 |
| 异步报表 (/report/task/create/ 使用POST 方法) |
2 | 60 | 4,500 | 2 | 60 | 4,500 | 2 | 60 | 4,500 | 2 | 60 | 4,500 |
| /pixel/track/ | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| 报告应用事件 (/app/track/ 使用POST方法) | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| /app/batch/ 使用POST方法 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| 报告网页事件 (/pixel/track/ 使用POST方法) | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| /pixel/batch/ 使用POST方法) | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| 报告线下事件 (/offline/track/ 使用POST方法) | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| /offline/batch/ 使用POST方法) | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 | 1,000 | 600,000 | 86,400,000 |
| 流式API | 10,000 | 600,000 | 864,000,000 | 20,000 | 1,200,000 | 1,728,000,000 | 30,000 | 1,800,000 | 2,592,000,000 | 50,000 | 3,000,000 | 4,320,000,000 |
| /campaign/copy/task/create/ | 1 | 30 | 432,000 | 1 | 30 | 432,000 | 1 | 30 | 432,000 | 1 | 30 | 432,000 |
| /campaign/copy/task/check/ | 2 | 60 | 864,000 | 2 | 60 | 864,000 | 2 | 60 | 864,000 | 2 | 60 | 864,000 |
| /gmv_max/report/get/ | 8 | 240 | 20,000 | 12 | 360 | 30,000 | 20 | 600 | 50,000 | 20 | 600 | 50,000 |
最佳实践
为避免请求被节流，更合理地利用服务资源，您可以批量发送请求，或者限制请求并发数量。
1. 批量发送请求
API 的读接口（GET）支持批量请求。相比每次请求只对一个数据进行操作，批量操作多个数据将更加高效。
例如，您可以通过传入多个 adgroup_ids 获取批量广告组，而非每次传入一个 adgroup_ids 并进行多次请求。
推荐:
(code Good http)
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id={{ADVERTISER_ID}}" \
--data-urlencode "filtering={\"adgroup_ids\": [ADGROUP_ID1,ADGROUP_ID2,ADGROUP_ID3,...]" \
--data-urlencode "page=1" \
--data-urlencode "page_size=100" \
https://ads.tiktok.com/open_api/2/adgroup/get/
(/code);
不推荐:
(code Not-recommended http)
for ADGROUP_ID in {ADGROUP_ID1,ADGROUP_ID2,ADGROUP_ID3,...} do
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id={{ADVERTISER_ID}}" \
--data-urlencode "filtering={\"adgroup_ids\": [$ADGROUP_ID1]" \
--data-urlencode "page=1" \
--data-urlencode "page_size=1" \
https://ads.tiktok.com/open_api/2/adgroup/get/ \
(/code);
2. 限制请求并发数量
在定时同步数据类场景下，如果您在某个时间点大量调用 API 接口，您的请求可能被节流。
在这种情况下，您可以在客户端自己使用速率限制器，控制并发请求数量。例如，您可以使用令牌桶算法：按照频控规则下发令牌（如每秒下发 10 个令牌），在请求前尝试获取令牌，如果当前没有令牌则等待一段时间后重试。
另一种更加稳健的方式是使用消息队列。定时脚本不直接负责请求 API，而是采用生产者-消费者模型，将请求任务推送至消息队列，由专门的消费者从队列中取出任务进行消费（即请求 API）。您可以通过限制对某一类任务的并发消费者数量或使用限流器，实现限制请求并发数量的目的。对于执行失败的任务，您可以将其重新推送至队列中（并设置一定延时）进行重试。