notion-known-pitfalls

name	notion-known-pitfalls
description	Use when debugging or reviewing Notion API code that fails with object_not_found, validation_error, rate_limited, or returns incomplete data. Covers the twelve most common mistakes: wrong page ID format (dashes), rich text array structure, block children not returned with page, pagination required for all lists, 3 req/sec shared across endpoints, and not sharing pages with the integration. Trigger with phrases like "notion mistakes", "notion pitfalls", "notion common errors", "notion gotchas", "notion debugging".
allowed-tools	Read, Grep
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

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. These pitfalls account for the majority of developer support questions.

The lean flow lives here; the full wrong-vs-right code for every pitfall (TypeScript and Python) is in references/implementation.md.

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)

Authentication

All calls authenticate with an internal integration token passed to the client constructor (new Client({ auth: process.env.NOTION_TOKEN }) / Client(auth=os.environ["NOTION_TOKEN"])). The token alone is not enough — every page and database must also be explicitly shared with the integration in the Notion UI (Pitfall #1). Never hardcode the token; read it from the environment.

Instructions

Work the pitfalls in order of frequency. Pitfall #1 is the single most common error, so it is worked in full below; #2–#12 follow the same wrong-vs-right shape and the complete code is in references/implementation.md.

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. A 404 object_not_found does NOT mean the page is missing — it means your integration lacks access.

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..({ :  });
}  (error) {
   ((error) && error. === .) {
    
    
    .();
    .();
    .();
  }
}


  (): <> {
   {
     notion..({ : databaseId });
     ;
  }  {
    .();
     ;
  }
}