Notion Page Property Item API 与 Request Limits 载荷限制实战:突破 25 条 Relation 截断、超长文本分页拉取、409 并发冲突重试与 TypeScript SDK 工程治理

2026 年 11 月 21 日

一、为什么 GET /v1/pages/{id} 会静默丢失数据?看懂 25 条截断与载荷红线 #

在构建财务对账系统、研发项目同步中枢或企业级 BI 数据管道时,许多开发团队都踩过同一个极其隐蔽的坑:一个父项目在 Notion 页面里明明关联了 68 个子任务,或者某个备注字段写了 4,000 多字的富文本,但后端脚本调用 GET /v1/pages/{page_id} 后,拿到的 relation 数组长度却永远停在 25 条,下游统计出来的工时与金额全部少算一半——而且接口返回状态码是正常的 HTTP 200 OK,没有任何报错提示!

这一现象源于 Notion 官方为保障单页响应延迟而设置的 属性载荷截断与 Request Limits(请求大小限制) 机制(关联表设计基础可参阅 Notion Relation 与 Rollup 工程治理实战 与 Pages API 写库工程指南)。在生产环境下,忽略接口硬性边界往往会触发以下四类严重故障:

  1. 未检查 has_more: true 导致关联与汇总数据静默截断:GET /v1/pages/{page_id} 与 POST /v1/data_sources/{id}/query(及旧版 /databases/{id}/query)对每行记录内的 relation、rollup、people、rich_text 和 title 属性最多只内联返回前 25 个元素;超过 25 条时仅置位 "has_more": true,必须改调 Page Property Item API 分页补全。
  2. 写入单段富文本超过 2,000 字符触发 400 validation_error:无论是写入页面 rich_text 属性还是更新正文段落,单个 text.content 或数学公式 equation.expression 均不得超过 2,000 个字符;同时单次请求中 rich_text、multi_select、relation 数组元素总数不能超过 100 个。
  3. 单次建页或追加块突破 100 块 / 500 KB 载荷红线:通过 POST /v1/pages 或 PATCH /v1/blocks/{id}/children 写入结构化内容时,单层 children 数组上限为 100 个 Block、单次嵌套最多 2 层、整包总块数上限 1,000 个且 HTTP 请求体严禁超过 500 KB(正文递归写入参阅 Blocks API 递归树读写实战)。
  4. 多协程并发更新同一页面触发 HTTP 409 conflict_error 直接崩溃:许多脚本只对 HTTP 429(每秒 3 次平均速率限制)做重试,却把并发写同一页面或同一区块时返回的 409 conflict_error 当作不可恢复错误直接抛弃,导致批量同步流水线大面积丢单。
接口与传输限制维度 Notion API 官方硬性上限 超限后的接口表现 / 返回状态 生产级工程应对策略
GET /pages/{id} 关联/富文本内联上限 单属性最多内联 25 条元素 HTTP 200,属性对象标记 has_more: true(静默截断) 检测 has_more 后立即调用 GET /pages/{id}/properties/{prop_id} 游标翻页
text.content / equation.expression 长度 单个文本/公式对象 ≤ 2,000 字符 HTTP 400 (validation_error) 拒绝写入 按 1,900 字符安全阈值切分为多个 rich_text 片段对象数组
url / email / phone_number 字段长度 URL ≤ 2,000 字符;Email/Phone ≤ 200 字符 HTTP 400 (validation_error) 入库前做正则校验、短链压缩或截断清洗并记录告警
单次属性数组元素数量 relation / multi_select / rich_text ≤ 100 项 HTTP 400 (validation_error) 关联超过 100 项需分批 PATCH 追加或拆分为反向归属写入
单次 Block 追加与请求体大小 单次 ≤ 100 children(≤ 2 层嵌套)、整包 ≤ 500 KB / 1,000 块 HTTP 400 或 HTTP 413 载荷过大报错 大文档改走 Markdown Content API 或按 80 块分片提交
平均吞吐速率与并发锁冲突 平均 3 req/s;同页并发写入触发乐观锁 HTTP 429 (rate_limited) / HTTP 409 (conflict_error) 429 严格遵循 Retry-After;409 采用随机抖动指数退避重放

二、Page Property Item API 分页拉取与四步防截断落地流程 #

结合 创建 Notion API 集成指南、Data Sources Query 复合查询实战 与 API 速率限制与容错架构,研发团队应在服务端统一封装一套“按需下钻 + 载荷分片 + 双重退避”的数据访问层,按以下四步落实:

步骤 1:识别 property_id 与需要分页的 list 响应结构 #

  1. 从数据源 Schema(GET /v1/data_sources/{data_source_id})或页面返回体中读取目标属性的 id(URL 编码安全,推荐优先使用固定 property_id 而非易变的中文属性名,避免业务同学改列名后接口失效,Schema 管理参阅 Databases 与 Data Sources Schema API 实战)。
  2. 当 GET /v1/pages/{page_id} 返回的属性对象出现 "has_more": true,或属性类型为复杂 rollup 时,调用 GET /v1/pages/{page_id}/properties/{property_id}(查询参数可传 page_size=100 与 start_cursor)。
  3. 注意区分该接口的两种返回结构:简单标量属性(如 number、select、date、checkbox)直接返回 object: "property_item";而 relation、rich_text、title、people 与 array 型 rollup 会返回 object: "list" 分页信封,通过 results 数组承载单条 property_item,并依据 has_more 与 next_cursor 循环拉取直至 has_more === false。

步骤 2:在写入前置层强制执行 1,900 字符与 80 元素安全分片 #

  1. 任何来自 LLM 摘要、客服工单正文或第三方 ERP 的长字符串在拼装 rich_text 前,必须通过分段函数按 1,900 字符(为多字节 Emoji 与换行转义预留安全余量)切分为多个 {"type": "text", "text": {"content": "..."}} 元素;若切分后数组超过 100 项,应自动降级写入页面正文 Block 或启用 Markdown Content API,切勿硬塞进数据库属性列。
  2. 每次追加数据库页面关联(relation)或标签(multi_select)时,在 SDK 封装层计算现有列表与增量列表的并集长度,若单次写入接近 100 项限制则拆分为多轮幂等更新。

步骤 3:统一配置 HTTP 429 + HTTP 409 双异常重试调度器 #

  1. 针对 HTTP 429(速率限制):优先解析响应头 Retry-After(单位秒)并叠加 200~500ms 随机抖动(Jitter),同时结合全局令牌桶将单 Integration 并发度控制在 2~3 req/s。
  2. 针对 HTTP 409(conflict_error 乐观锁冲突):在多 Webhook 消费者同时更新同一张汇总项目页时极为常见(事件订阅架构参阅 Integration Webhooks 实战)。捕获 conflict_error 后按 300ms -> 700ms -> 1500ms 指数退避重放,并配合页面级互斥队列消除无谓碰撞。

步骤 4:对齐 Notion-Version: 2026-03-11 与 @notionhq/client 类型安全契约 #

  1. 升级官方 TypeScript SDK @notionhq/client 时,在客户端初始化显式锁定 notionVersion: "2026-03-11"(兼容 2025-09-03 多源数据库模型),并使用 in_trash 替代已废弃的 archived 字段、使用 position 对象替代块追加的扁平 after 字符串。
  2. 对 pages.properties.retrieve() 返回联合类型进行显式类型收窄(Type Guard),区分 object === "list" 与单值 property_item,彻底杜绝运行时 undefined 崩溃。

三、TypeScript(@notionhq/client)生产级工程实现 #

以下 TypeScript 模块完整演示了基于官方 SDK 的 429/409 双重试拦截器、Page Property Item 全量关联与文本分页提取器 以及 2,000 字符安全拆片工具:

import { Client, isNotionClientError, APIErrorCode } from "@notionhq/client";
import type {
  GetPagePropertyResponse,
  PropertyItemObjectResponse,
} from "@notionhq/client/build/src/api-endpoints";

export const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  notionVersion: "2026-03-11",
});

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/** 统一重试封装:同时处理 429 速率限制与 409 并发冲突 */
export async function withNotionRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 5
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: unknown) {
      if (!isNotionClientError(err)) throw err;

      const isRateLimit = err.code === APIErrorCode.RateLimited;
      const isConflict = err.code === APIErrorCode.ConflictError;
      const isTransient5xx =
        err.code === APIErrorCode.InternalServerError ||
        err.code === APIErrorCode.ServiceUnavailable;

      if ((isRateLimit || isConflict || isTransient5xx) && attempt < maxRetries - 1) {
        const retryAfterHeader =
          "headers" in err && err.headers && typeof err.headers === "object"
            ? Number((err.headers as Record<string, string>)["retry-after"])
            : NaN;
        const baseWaitMs = Number.isFinite(retryAfterHeader)
          ? retryAfterHeader * 1000
          : Math.min(8000, 400 * 2 ** attempt);
        const jitterMs = Math.floor(Math.random() * 350);
        await sleep(baseWaitMs + jitterMs);
        continue;
      }
      throw err;
    }
  }
  throw new Error("Notion API retry attempts exhausted");
}

/** 分页拉取完整页面属性条目,彻底突破 GET /pages/{id} 的 25 条截断 */
export async function fetchAllPropertyItems(
  pageId: string,
  propertyId: string
): Promise<PropertyItemObjectResponse[]> {
  const items: PropertyItemObjectResponse[] = [];
  let cursor: string | undefined;

  while (true) {
    const res: GetPagePropertyResponse = await withNotionRetry(() =>
      notion.pages.properties.retrieve({
        page_id: pageId,
        property_id: propertyId,
        page_size: 100,
        start_cursor: cursor,
      })
    );

    if (res.object === "list") {
      items.push(...res.results);
      if (!res.has_more || !res.next_cursor) break;
      cursor = res.next_cursor;
    } else {
      items.push(res);
      break;
    }
  }

  return items;
}

/** 专门提取超过 25 个关联页面的全部 Target Page ID */
export async function fetchAllRelationIds(
  pageId: string,
  relationPropertyId: string
): Promise<string[]> {
  const items = await fetchAllPropertyItems(pageId, relationPropertyId);
  return items
    .filter((item): item is Extract<PropertyItemObjectResponse, { type: "relation" }> =>
      item.type === "relation"
    )
    .map((item) => item.relation.id);
}

/** 安全切分超长文本为符合 2000 字符与 100 元素上限的 rich_text 数组 */
export function buildSafeRichText(rawText: string, chunkSize = 1900) {
  const chunks: Array<{ type: "text"; text: { content: string } }> = [];
  for (let i = 0; i < rawText.length; i += chunkSize) {
    if (chunks.length >= 100) {
      throw new Error("文本总长度超出单个属性 100 个 rich_text 片段上限,请改用正文 Block 写入");
    }
    chunks.push({
      type: "text",
      text: { content: rawText.slice(i, i + chunkSize) },
    });
  }
  return chunks.length > 0 ? chunks : [{ type: "text" as const, text: { content: "" } }];
}

四、Formula 2.0 实战:API 载荷超限与 25 条截断风险巡检门禁 #

在企业内部运行多个同步脚本时,建议建立《Notion API 集成载荷健康台账》,记录每条数据管道对应的 最大单行关联数(Number)、单属性最大字符数(Number)、单次请求块数(Number)、已启用属性分页接口(Checkbox)、已接入 409/429 重试(Checkbox)与 近7日报错次数(Number),并配置如下 载荷与截断健康门禁 Formula 2.0 属性(语法细节参阅 Formula 2.0 速查手册 与 数据库架构规范):

lets(
  maxRelations, prop("最大单行关联数"),
  maxChars, prop("单属性最大字符数"),
  maxBlocks, prop("单次请求块数"),
  propPaginated, prop("已启用属性分页接口"),
  retryReady, prop("已接入 409/429 重试"),
  errCount, prop("近7日报错次数"),

  ifs(
    maxRelations > 25 && !propPaginated,
      style("🚨 静默截断高危:关联数已达 " + format(maxRelations) + " 条但未接入 Property Item 分页", "red", "bold", "red_background"),
    maxChars > 2000 || maxBlocks > 100,
      style("⛔ 载荷越界阻断:单文本超 2000 字或单次 Blocks 超 100 块,必发 400 报错", "red", "bold", "red_background"),
    !retryReady,
      style("⚠️ 缺少 409/429 退避重试:高并发写库存在丢单风险", "orange", "bold", "yellow_background"),
    errCount > 0,
      style("🟡 近 7 日存在 " + format(errCount) + " 次接口异常,请复核 Payload 与限流日志", "orange"),
    style("🟢 载荷分片、25+ 属性分页与并发重试全合规", "green")
  )
)

五、生产上线前核对清单与常见排障指引 #

在将任意 Notion API 集成推向生产环境前,建议逐项核验以下三点(如遇 400 validation_error、409 conflict_error 或响应不完整,可直接查阅 Notion 常见报错与故障诊断手册):

  1. 禁止在 Data Sources Query 后再盲目遍历全部单页:仅当某行记录的关键 relation、rollup 或 rich_text 字段明确带有 has_more: true 时,才触发 GET /v1/pages/{id}/properties/{prop_id} 精准补抓,避免消耗无谓的每秒 3 次限流配额。
  2. 用 filter_properties 配合 Property Item 接口实现极限瘦身:列表查询阶段通过 filter_properties 只拉取主键、状态与关键标志位,将大文本与多关联剥离到按需翻页加载,能将同步吞吐率提升 3~5 倍。
  3. 写库载荷严禁原样回传只读属性:跨库同步或复制记录时,务必在构造请求体前剥离 formula、rollup、created_time、last_edited_time、unique_id 与 button 等只读属性,确保接口幂等稳定运行。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。