Notion API追加待办事项至页面失败问题求助

此前使用Python代码通过Notion API向指定页面追加待办事项（to_do）功能一直正常运行，但上周起该功能失效：

• 使用相同API Key和Notion v1 URL的其他功能（读写数据库、页面）仍可正常交互
• 代码执行无任何报错，但待办事项并未添加到目标页面
• 已尝试操作：确认集成仍关联Notion账号、刷新API Key
• 额外异常：无法将集成邀请到目标页面，其他页面也存在此问题

关联代码 #

import requests
from app import config
from app import itemSorter
from datetime import datetime

def getToDoItem(content): 
    return{"type": "to_do","to_do": {"rich_text": [{"type": "text","text": {"content": content,}}],"color": "default",}}

def appendToDo(id, item_input_list):
    url = f"{config.notion_url}blocks/{id}/children"
    headers = {
        "Authorization": "Bearer " + config.notion_api_key,
        "Accept": "application/json",
        "Notion-Version": "2022-02-22",
        "Content-Type": "application/json"
    }
    new_page_childs = []
    new_page_childs.append(getToDoItem(str(datetime.now())))
    for child in item_input_list:
        new_page_childs.append(getToDoItem(child))
    payload ={"children":new_page_childs}
    response = requests.patch(url,json=payload, headers=headers)

def populateNotion():
    appendToDo(config.notion_shoppinglist, itemSorter.getSortedShoppingList())

排查与解决步骤 #

1. 强制校验API请求响应 #

当前代码未处理请求响应，即使操作失败也不会触发报错。添加响应校验代码，直接获取Notion返回的错误信息：

response = requests.patch(url, json=payload, headers=headers)
# 若请求失败（非2xx状态码），直接抛出异常
response.raise_for_status()
# 打印响应内容，查看具体操作结果或错误
print(response.json())

Notion API常出现返回200但实际操作失败的情况（如权限不足），响应内容会明确说明问题原因。

2. 修复集成权限问题 #

无法邀请集成到页面是权限异常的核心表现，按以下步骤排查：

• 进入Notion集成管理后台，确认集成的Capabilities已开启Content > Insert content和Content > Edit content权限
• 检查集成的Workspace access设置：若为"Specific pages"，需确保目标页面已被添加到授权列表；若为"All content"，需确认集成未被 workspace 管理员限制
• 若目标页面属于共享空间，需空间管理员重新授权集成访问该空间

3. 验证API版本兼容性 #

当前使用的Notion-Version为2022-02-22，虽旧版本仍被支持，但部分接口行为可能变更。尝试升级到较新的版本（如2024-02-29），同时确保请求格式符合对应版本的规范。

4. 确认页面ID有效性 #

检查config.notion_shoppinglist对应的是页面ID而非数据库ID或其他资源ID。页面ID可从页面URL提取：例如https://www.notion.so/MyShoppingList-abc123def456ghi789jkl012mno345pqr678中的abc123def456ghi789jkl012mno345pqr678即为页面ID。

5. 规范待办事项格式 #

确保待办事项的JSON格式完全符合Notion API要求，显式添加未勾选状态避免默认值问题：

def getToDoItem(content): 
    return {
        "type": "to_do",
        "to_do": {
            "rich_text": [{"type": "text", "text": {"content": content}}],
            "checked": False,
            "color": "default"
        }
    }

内容的提问来源于stack exchange，提问作者yölö