速率限制

Advertiser API 的速率限制与 REST API v1.1 类似，详情见：REST API v1.1 的速率限制。但与 REST API v1.1 不同的是，不提供按端点的可编程限额索引。各端点的速率限制及重置时间窗口通过 HTTP 响应头传达。Ads API 中的所有速率限制均使用 OAuth 1.0A。

​

用户级与广告账户级限制

速率限制分为两种类型：用户令牌级和广告账户级。部分端点启用了广告账户级速率限制。用户令牌是你用于认证并调用 Ads API 的 OAuth 访问令牌。每个用户令牌可以访问一个或多个广告账户。

当响应头中返回广告账户级速率限制时，开发者应使用广告账户级限制；仅在找不到广告账户级限制时才使用用户级限制。

用户级速率限制通过以下响应头表示：x-rate-limit-limit、x-rate-limit-remaining 和 x-rate-limit-reset

对于启用广告账户级速率限制的端点，速率限制通过以下响应头表示：x-account-rate-limit-limit、x-account-rate-limit-remaining 和 x-account-rate-limit-reset。

广告账户级速率限制仅适用于 GET 端点，以便应用从单个用户令牌同步访问多个广告账户时的实体数据（例如广告系列或广告组等对象）。写入操作不保证使用相同的广告账户级速率限制。

对于采用广告账户级速率限制的端点，用户级速率限制被设置为较高值，代表整个应用的全局配额。在可用时，应优先使用广告账户级速率限制来控制你的请求量。

​

最佳实践

1. 在数据库中保存上次同步的时间戳；在适用场景下，请求数据时使用 sort_by=updated_at-desc 选项，这样当你获取到早于上次同步时间戳的数据时即可停止同步过程，从而避免对相同数据的重复同步。

2. 在单个请求中获取多个实体：某些端点允许你指定以逗号分隔的取值列表，以一次性检索多组相似数据。这可以减少你发起的请求总数，从而更高效地利用速率限制。

3. 在请求中使用最大“count”值：强烈建议对某些端点（例如 GET accounts/:account_id/targeting_criteria）使用最大 count 值，以返回 1000 个对象，而不是默认的 200 个。

​

分析同步

有关 Analytics 端点的速率限制详情，请参阅Analytics 速率限制指南。

​

常见问题

是否可以为特定广告账户或我们的应用提高速率限制？

我们通常无法提高速率限制，这些限制已设定以支持规模最大的广告账户。请先落实本文档列出的最佳实践；如果速率限制仍影响您扩展或达成业务目标的能力，请联系您的 X Ads API 对接人，并提供关于用例和相关请求的完整详情。

​

速率限制范围

​

本文档适用的范围

• 类别：同一类别下的所有端点在每个时间窗口共享一套分配的速率限制。
• 端点：每个端点在每个时间窗口都有各自独立分配的速率限制。

​

Ads API 速率限制一览表

​

Ads API 速率限制

端点类型	按端点或类别划分的范围	每 1 分钟窗口的速率限制
写入（POST、PUT、DELETE）	类别	450
受众	端点	1500

端点类型	按端点或类别划分的范围	每 15 分钟窗口的速率限制
分析（同步）	类别	250
核心实体读取（Line Items、Campaigns 等） 其他账户读取（其他带有 :account_id 的 GET 端点）	端点（广告账户级） 端点（部分广告账户级）	10,000 2000
定向条件（除下述以外）	类别	400
定向条件（tv_markets、tv_shows）	端点	2000
受众洞察	类别	400
关键词洞察	类别	500
全局读取（不带 :account_id 的 GET 端点）	端点	5
转化	端点	60,000