notion-known-pitfalls

# Notion Known Pitfalls ## Overview The twelve most common mistakes when building Notion API integrations, each with the wrong pattern, why it fails, and the correct fix using real `Client` from `@notionhq/client` code. These pitfalls account for the majority of developer support questions. Covers page ID format issues, rich text structure, missing block children, pagination requirements, rate limit sharing, and integration sharing. ## Prerequisites - `@notionhq/client` v2.x installed (`npm install @notionhq/client`) - Python: `notion-client` installed (`pip install notion-client`) - `NOTION_TOKEN` environment variable set - Familiarity with Notion API concepts (databases, pages, blocks, properties) ## Instructions ### Step 1: Not Sharing Pages with the Integration (Pitfall #1) The single most common Notion API error. Every page/database must be explicitly shared with your integration. ```typescript import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client'; const notion = new Client({ auth: process.env.NOTION_TOKEN }); // This returns 404 even though the page EXISTS in your workspace try { const page = await notion.pages.retrieve({ page_id: 'some-page-id' }); } catch (error) { if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) { // "object_not_found" does NOT mean the page doesn't exist // It means your integration doesn't have access console.error('Page exists but integration lacks access.'); console...