请求成功却什么都没改？Notion API 那些不报错的坑

你有没有遇到过这种情况：接口返回成功，你以为万事大吉，结果后来才发现，实际发生的事和你以为请求的并不是一回事？

一位开发者在把 Publora 接入 Notion 时，就踩进了这个坑。Publora 是一个集成工具，功能是从数据库里读行，把它们变成定时发布的帖子。构建、测试、提交，流程走完，他才发现：大部分问题根本不报错。请求成功了，但结果和他以为的完全不是一回事。

他把这些耗掉时间的坑整理了出来。如果你正在基于 Notion 做开发，或许能省下几个下午。

容易漏掉的权限范围

在 Notion 的授权页面上，你需要勾选哪些页面可以共享、哪些不动。但不太明显的是，这个集成实际上被允许对这些页面做什么。他的集成默认开启了额外权限：插入内容，以及读取用户及其邮箱。

他发现这件事，是因为用真实令牌试了集成本不该能做的事：

• GET /v1/users → 200，返回了带邮箱的用户
• POST /v1/pages → 200，页面被创建了

他把权限削减到"读取 + 更新内容"再试：

• GET /v1/users → 403 restricted_resource
• POST /v1/pages → 403 restricted_resource

这才是他真正需要的。Publora 要读行、把状态写回去，不需要创建页面的权限。授权页面在展示"你共享了哪些页面"方面做得不错，但在解释"令牌到底能干什么"上就差多了，所以他最后是用实际请求去核对权限的。

还有一个相关的坑：改权限不会改变已有令牌。他在后台取消勾选，再测，旧权限还在。必须彻底断开连接，重新走一遍 OAuth。

API 说"好的"，然后什么也不做

它不能发布页面，而且不会承认这一点。public_url 是只读的。用 PATCH 请求它，请求会顺利通过，没有报错，但什么都不会变。他花了二十分钟改请求体，最后才发现请求本身没有任何问题。分享 → 发布是一个手动操作，API 根本没有暴露这个能力。

它给你 icon: null，然后拒绝收回去。读一个块，你可能拿到 icon: null。把同一个对象发回去写入，就会失败。他们最后在写入前把所有空字段都剥掉。

视图没法通过 API 创建。想要日历视图或看板视图，还是得手动切换布局。

块不能移动。没有"把这个移到那个上面"的等价操作。你得用 after: 插入一个副本，再把旧块归档。严格来说不算移动，但结果看起来像移动了，显然这就够了。

Skill 标志没法通过 REST 设置。UI 里有这个开关，Notion 的 MCP 工具里也有，但纯 REST 没有。

眼下大家都在踩的那个坑

从 API 版本 2025-09-03 开始，行不再直接挂在数据库下面了。它们属于一个数据源。一个数据库现在可以有多个数据源，这意味着旧的 POST /v1/databases/{id}/query 可能失败，报错说多数据源不被支持。

新路径是：先获取数据库，取 data_sources[0].id，然后调用 POST /v1/data_sources/{id}/query。

这个坑让他困惑，因为在 Notion 里一切看起来还是数据库的样子。但从 API 的视角看，中间多了一层东西。

几个流程上的事

访问权限是逐页授予的，光有令牌不够。你得通过 ••• → Connections 把每个页面连上。否则 /v1/search 完全可能正确地返回零结果。他花了一些时间怀疑搜索功能，后来才意识到，他们压根没把页面给集成。

OAuth 往返十分钟太短了。他们的会话密钥原本只活 600 秒。如果你明确知道要找哪个数据库，这时间绰绰有余。但当你滚动一个长列表、努力回忆半年前给它起了什么名字时，就不够慷慨了。他们改成了三十分钟。

机器人会遇到验证码。他试着自动截取自己公开页面的截图，Playwright 两次遇到"Verify you are human"。最后他自己动手截了图。非常高级的自动化。

过程中还有一个不错的惊喜：他们用同义词来映射列。caption、text 和 message 都可以是帖子正文；platform 和 networks 可以标识渠道。测试时，他给了一个列名有拼写错误的数据库，结果照样匹配上了。这样人们就不必围绕他们的模板重建内容日历，而这正是他非常不想要求别人去做的一件事。

他的体会

用了一段时间 Notion API 之后，他不再把"响应成功"当成"已经完成"的证明。他现在会检查实际结果：令牌到底有什么权限，写入是否真的改了他想改的东西，集成是否真的能看到那个页面。

这话写下来显得很明显。但在他花二十分钟试图 PATCH 一个根本改不了的字段时，显然就没那么明显了。

这篇文章是在 Claude 的帮助下写的。

你有没有用过这样的 API：请求成功了，你后来才发现它并没有完全做到你以为的事？