Notion Page Property Item API 与 Request Limits 载荷限制实战:突破 25 条 Relation 截断、超长文本分页拉取、409 并发冲突重试与 TypeScript SDK 工程治理
一、为什么 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 写库工程指南)。在生产环境下,忽略接口硬性边界往往会触发以下四类严重故障:
- 未检查
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,000 字符触发
400 validation_error:无论是写入页面rich_text属性还是更新正文段落,单个text.content或数学公式equation.expression均不得超过 2,000 个字符;同时单次请求中rich_text、multi_select、relation数组元素总数不能超过 100 个。 - 单次建页或追加块突破 100 块 / 500 KB 载荷红线:通过
POST /v1/pages或PATCH /v1/blocks/{id}/children写入结构化内容时,单层children数组上限为 100 个 Block、单次嵌套最多 2 层、整包总块数上限 1,000 个且 HTTP 请求体严禁超过 500 KB(正文递归写入参阅 Blocks API 递归树读写实战)。 - 多协程并发更新同一页面触发
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 响应结构 #
- 从数据源 Schema(
GET /v1/data_sources/{data_source_id})或页面返回体中读取目标属性的id(URL 编码安全,推荐优先使用固定property_id而非易变的中文属性名,避免业务同学改列名后接口失效,Schema 管理参阅 Databases 与 Data Sources Schema API 实战)。 - 当
GET /v1/pages/{page_id}返回的属性对象出现"has_more": true,或属性类型为复杂rollup时,调用GET /v1/pages/{page_id}/properties/{property_id}(查询参数可传page_size=100与start_cursor)。 - 注意区分该接口的两种返回结构:简单标量属性(如
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 元素安全分片 #
- 任何来自 LLM 摘要、客服工单正文或第三方 ERP 的长字符串在拼装
rich_text前,必须通过分段函数按 1,900 字符(为多字节 Emoji 与换行转义预留安全余量)切分为多个{"type": "text", "text": {"content": "..."}}元素;若切分后数组超过 100 项,应自动降级写入页面正文 Block 或启用Markdown Content API,切勿硬塞进数据库属性列。 - 每次追加数据库页面关联(
relation)或标签(multi_select)时,在 SDK 封装层计算现有列表与增量列表的并集长度,若单次写入接近 100 项限制则拆分为多轮幂等更新。
步骤 3:统一配置 HTTP 429 + HTTP 409 双异常重试调度器 #
- 针对
HTTP 429(速率限制):优先解析响应头Retry-After(单位秒)并叠加200~500ms随机抖动(Jitter),同时结合全局令牌桶将单 Integration 并发度控制在2~3 req/s。 - 针对
HTTP 409(conflict_error乐观锁冲突):在多 Webhook 消费者同时更新同一张汇总项目页时极为常见(事件订阅架构参阅 Integration Webhooks 实战)。捕获conflict_error后按300ms -> 700ms -> 1500ms指数退避重放,并配合页面级互斥队列消除无谓碰撞。
步骤 4:对齐 Notion-Version: 2026-03-11 与 @notionhq/client 类型安全契约 #
- 升级官方 TypeScript SDK
@notionhq/client时,在客户端初始化显式锁定notionVersion: "2026-03-11"(兼容2025-09-03多源数据库模型),并使用in_trash替代已废弃的archived字段、使用position对象替代块追加的扁平after字符串。 - 对
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 常见报错与故障诊断手册):
- 禁止在
Data Sources Query后再盲目遍历全部单页:仅当某行记录的关键relation、rollup或rich_text字段明确带有has_more: true时,才触发GET /v1/pages/{id}/properties/{prop_id}精准补抓,避免消耗无谓的每秒 3 次限流配额。 - 用
filter_properties配合 Property Item 接口实现极限瘦身:列表查询阶段通过filter_properties只拉取主键、状态与关键标志位,将大文本与多关联剥离到按需翻页加载,能将同步吞吐率提升 3~5 倍。 - 写库载荷严禁原样回传只读属性:跨库同步或复制记录时,务必在构造请求体前剥离
formula、rollup、created_time、last_edited_time、unique_id与button等只读属性,确保接口幂等稳定运行。
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。