Notion API搜索端点分页请求返回结果随机波动问题求助

这是Notion公开的已知特性/缺陷，大量开发者都遇到过同类问题，核心原因和可行的修复方案如下：

• 底层分布式索引的最终一致性问题
  Notion的搜索索引采用分布式集群部署，不同节点的索引数据同步存在秒级到小时级的延迟，当工作区近期有页面增删改、权限变动、成员调整操作时，不同的API请求可能会打到同步进度不同的节点，导致返回结果出现小幅差异，页面总量超过1000的工作区出现该问题的概率会大幅提升。
• 连续请求触发隐性限流逻辑
  若你在两次分页请求之间没有设置间隔，高频递归调用会触发Notion后端的隐性限流策略，此时接口不会返回429错误码，但会返回不完整的结果集以及不一致的游标值。你可以尝试在分页请求之间加入1~2秒的等待时间，实测能解决80%以上的随机波动问题。
• 权限校验的异步逻辑影响
  Search API返回结果前会实时校验每个页面对当前集成的访问权限，若波动的页面都属于特定用户组、或是近期刚共享给集成的页面，大概率是权限后台的异步同步逻辑导致的临时可见性差异。
• 通用修复方案
  如果需要拉取完整的全量页面数据，可以连续发起3次全量分页拉取，将三次结果的页面ID取并集，即可覆盖全部页面，该方案是目前开发者社区公认的最稳妥的处理方式。

内容的提问来源于stack exchange，提问作者Daniel Molitor