Notion API · api · fg-0453

Appending more than 100 blocks or nesting three levels deep in one Notion request fails with validation_error

body failed validation: body.children.length should be ≤ `100`

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

Append block children and page creation accept at most 100 blocks per array and only two levels of nesting in a single request. The whole payload is also capped at 1000 block elements and 500KB.

Fix

Send top-level blocks in batches of 100 and append deeper children in follow-up calls using the block IDs the first call returns.

Apply

for (let i = 0; i < blocks.length; i += 100) {
  await notion.blocks.children.append({ block_id: pageId, children: blocks.slice(i, i + 100) });
}

Affects: Notion REST API, all versions, as of 2026-10

Sources

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp