TikTok Ads API 限流：处理 429 与重试风暴

一次 TikTok Ads API rate limit 故障，很少只停留在 429。报表任务开始变慢，多账户批次在同一时刻重叠，自动重试把原始流量放大，投手又因为看不到最终状态而手动重跑。正确的第一步不是增加并发，而是停止无界重试，确认当前调用的 API surface、具体 endpoint、授权上下文和每个对象的已知结果。

TikTok 没有一个可以放心套到所有广告接口的统一 QPS。官方提供 API for Business Rate limits Overview，同时 TikTok for Developers 的限流页描述的是另一套 API surface。某个页面或某个 endpoint 的数字，不能直接变成全部 Marketing API 的运行参数。团队应以实际调用接口的当日官方合同为准，并在合同之下留出恢复余量。

遇到 429 后先做什么

先暂停自动重试，再回答四个问题：调用的是哪套 TikTok API，失败的是哪个 endpoint，作用于哪个 app 与广告主上下文，这次操作是读取还是写入。只有证据齐全，才能判断任务应延后、停止，还是在再次写入前先对账。

不要先换 IP、轮换 token、增加广告账户或临时增加执行进程。这些动作可能继续放大压力，也可能偏离平台允许的边界。429 是容量控制信号，不是绕过限制的提示。

每次尝试至少保留以下事故证据：

证据	用途
API surface 与官方文档页	避免把 Display、Content Posting、Shop 和 API for Business 混为一谈
endpoint 与读写类型	区分可延后的报表读取和高风险写操作
app 与广告主上下文	判断压力集中在单个账户还是共享流量
尝试时间与关联标识	还原先后顺序，同时不暴露凭证
对象级已知状态	防止成功项被重复执行

如果当前官方合同无法直接确认响应头、错误体或等待时间，就不要补猜。把限额视为通过官方合同与实际观测共同确定的边界，采用保守策略运行。

重试前先给失败分类

HTTP 429 或官方明确的频控信号，可以进入延迟重试候选。但这不等于所有失败都应该进入同一个循环。

可以把失败分成三类：

类别	处理方式	常见场景
容量或临时传输故障	在有界预算内延后	已确认频控、连接中断、临时上游不可用
输入不变就不会恢复	立即停止并给出原因	参数无效、权限不足、对象状态不支持、资源不存在
写入后结果未知	先查询和对账，再决定是否重试	请求已发出，但最终响应没有返回

第二类必须交给投手修正输入或权限，不能交给定时器。权限错误重复 20 次，不会自动获得权限，只会消耗本应留给正常请求的容量。

第三类风险最高。创建计划、启停或改预算的请求可能已经到达 TikTok，只是响应在途中丢失。此时盲目再次写入，可能重复创建或重复修改。恢复流程必须回到 TikTok 真源查询，比较目标状态与实际状态，只处理仍未解决的对象。这是一套安全恢复合同，不是 exactly-once 承诺。

多账户队列要解决公平问题

生产队列的职责是吸收突发并决定下一项工作，而不是把请求临时堆起来，再在同一秒全部释放。

读和写应分开治理。历史报表晚几分钟通常只是体验问题；一次结果不明的重复写入可能直接影响预算和投放状态。任务还要按当前 endpoint 官方合同适用的边界组织。不能默认所有 endpoint 共用一个桶，也不能在缺少证据时假设它们完全独立。

处理 TikTok Ads API rate limit 时，代理商和多品牌团队还要解决公平性。某个大客户的历史回填，不应堵住其他广告主的紧急暂停操作。可验收的调度方式应在具备执行条件的广告主之间轮转，对已审核写操作设置明确优先级，并限制单个客户在恢复窗口占用的份额。

背压也要传回任务生产端。队列增长时，应暂停新增历史回填、拆小日期范围，并明确告诉操作者完成时间会延后。消费端已经受限，生产端仍全速入队，只会把短暂频控拖成长时间积压。

用有界退避和 retry budget 控制风暴

安全重试必须有终点。每个对象都要有最大尝试次数、最长恢复窗口，以及人工可见的终态。指数退避负责拉开尝试间隔，jitter 负责避免成千上万个任务同时醒来。具体间隔应服从当前 endpoint 合同和实际观测，不能照抄另一套 TikTok API 的固定秒数。

retry budget 比无限循环更重要。团队要预先规定：一个失败批次最多可以产生多少额外请求。当预算耗尽，系统应停止自动执行，把对象标为未解决，并留下足够证据。这样才能保护仍然健康的广告主，而不是让单个故障吞掉所有容量。

一条完整恢复链应做到：

1. 只有在适用边界存在容量时，才接纳下一对象。
2. 单次尝试后立即记录对象结果。
3. 永久失败马上停止，不进入等待。
4. 可重试失败使用退避与 jitter 延后。
5. 结果未知的写操作必须先对账。
6. 最终进入成功、已确认失败或清晰的人工复查状态。

批量操作必须保留部分成功

界面上的一个批量动作，到了 TikTok 仍然会逐项产生结果。20 个启停操作成功 18 个、失败 2 个时，恢复单位是那 2 个失败对象，不是原来的 20 个。

系统应独立展示每个目标的状态。成功项在恢复视图中保持完成，停止项带上投手能处理的原因，修正权限或参数后只选择未解决对象。一个笼统的绿色"批次完成"，无法支撑可靠运营。

对于写操作，在官方 endpoint 支持相容恢复方式时，可以使用稳定的客户端操作身份。若没有，应至少保留自己的操作意图，并在重新提交前核对最终状态。外部 API 边界上不要承诺 exactly-once。

报表任务要单独削峰

报表通常是最容易制造突发的来源。每日任务同时启动，每个广告主拉同一日期范围，分页继续放大请求，历史回填又与今天的看板争抢容量。

先降低这些可避免压力，再讨论重试参数：

• 错开定时读取，不让全部账户在整点同时开始。
• 在业务允许的新鲜度范围内，复用已确认且不会变化的数据。
• 把历史回填拆成有限日期窗口，并让位于当天报表。
• 保存分页进度，失败后从已知位置恢复，而不是回到第一页。
• 分清 API 频控、归因回填、报表延迟和时区差异。

本文不重写报表架构选型。需要评估 CSV、表格、自建接口与数据管道时，参考 TikTok Ads API 报表自动化指南。需要核验 GMV Max 能力范围和自建采购边界时，参考 GMV Max API 自动化指南。

如何验收自动化供应商

不要只问供应商"是否处理限流"。供应商对 TikTok Ads API rate limit 的回答，必须通过一个已授权、低风险广告主账户的受控验收来证明。

验收至少证明六件事：

1. 安全批次进入队列，而不是瞬间冲向平台。
2. 每个目标都有独立的最终结果或未解决状态。
3. 永久失败会停止，并给出可行动原因。
4. 失败项重试时，已完成项不会重复执行。
5. 结果未知的写操作，在重提之前有查询和对账路径。
6. 投手能看到积压、恢复状态和自动化停止位置。

还要问清授权归属、权限回收、数据保留，以及真实支持哪些广告类型和动作。更完整的采购边界可参考 TikTok 广告自动化工具购买清单；本次验收只聚焦容量与恢复。

AdRate 在这条流程中的边界

AdRate 不绕过 TikTok 限流，也不提供无限账户或保证送达。与本文相关、已经核验的产品能力更具体：团队可以查询多个已授权广告账户，对已支持的计划执行批量启停和预算操作，查看逐项结果，并按账户或按成员管理 Business Center 账户权限。

因此，合理试用范围很小。先连接一个已授权测试账户，执行一次可逆的已支持操作，制造一个安全失败，再检查成功项和失败项是否始终分开。扩大账户范围前，可先核对批量管理能力与账户权限流程。

常见问题

TikTok Ads API 有统一限额吗

没有一个可以安全假设的通用数字。先确认 API surface、endpoint、app 和广告主上下文，再核验当日官方合同。不要把 TikTok for Developers、Shop API 或其他 endpoint 的数字套到 API for Business。

所有 429 都应该重试吗

只有完成分类后，才能在有界策略内延迟。已确认的容量故障可以候选重试；权限、校验、资格与资源状态错误应停止；写入结果未知时必须先对账。

是否应该并发读取全部广告账户

没有公平调度和背压方案时不应该。无控制并发会让一个回填任务占用共享容量，并让整个账户组合在同一时刻进入重试。

重试会重复创建计划或修改预算吗

会有这种风险，尤其是写入已到达 TikTok 但响应丢失时。应保留操作意图、查询最终状态，只在确认目标仍未完成后重试。

采购工具时必须问什么

要求供应商说明支持的 API surface、动作矩阵、授权归属、逐项结果、重试停止规则、未知写恢复、积压可见性与权限控制，并用低风险账户现场验收。