notion-known-pitfalls

What this skill does

# 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.error('Fix: In Notion UI, open page -> ... menu -> Connections -> Add your integration');
    console.error('Tip: Share a parent page to grant access to ALL child pages');
  }
}

// Always verify access at startup
async function verifyAccess(databaseId: string): Promise<boolean> {
  try {
    await notion.databases.retrieve({ database_id: databaseId });
    return true;
  } catch {
    console.error(`Cannot access database ${databaseId}. Share it with your integration.`);
    return false;
  }
}
```

### Step 2: Page ID Format Issues and Rich Text Array Structure (Pitfalls #2-3)

Notion IDs work with or without dashes, but URLs contain dashes while the API often returns them without.

```typescript
// PITFALL #2: Page ID format confusion
// Notion URLs: https://notion.so/Page-Title-a1b2c3d4e5f67890abcdef1234567890
// The ID is the last 32 hex chars: a1b2c3d4e5f67890abcdef1234567890
// API accepts both formats:
//   a1b2c3d4-e5f6-7890-abcd-ef1234567890  (with dashes)
//   a1b2c3d4e5f67890abcdef1234567890        (without dashes)

function extractPageId(urlOrId: string): string {
  // Handle full Notion URL
  const urlMatch = urlOrId.match(/([a-f0-9]{32})(?:\?|$)/);
  if (urlMatch) return urlMatch[1];

  // Handle URL with dashes in page title (ID is always last 32 hex chars)
  const cleanId = urlOrId.replace(/-/g, '');
  const idMatch = cleanId.match(/([a-f0-9]{32})$/);
  if (idMatch) return idMatch[1];

  // Already a clean ID
  return urlOrId;
}

// PITFALL #3: Rich text is ALWAYS an array, even for single values
// WRONG: treating rich_text as a string
// const text = page.properties.Description.rich_text; // This is an ARRAY

// WRONG: accessing without checking length
// const text = page.properties.Description.rich_text[0].plain_text; // TypeError if empty!

// RIGHT: safe extraction helper
function extractRichText(page: any, propertyName: string): string {
  const prop = page.properties[propertyName];
  if (!prop) return '';

  if (prop.type === 'title') {
    return prop.title?.map((t: any) => t.plain_text).join('') ?? '';
  }
  if (prop.type === 'rich_text') {
    return prop.rich_text?.map((t: any) => t.plain_text).join('') ?? '';
  }
  return '';
}

// RIGHT: safe property extraction for all types
function extractProperty(page: any, name: string): any {
  const prop = page.properties[name];
  if (!prop) return null;

  switch (prop.type) {
    case 'title':
      return prop.title?.map((t: any) => t.plain_text).join('') ?? '';
    case 'rich_text':
      return prop.rich_text?.map((t: any) => t.plain_text).join('') ?? '';
    case 'number':
      return prop.number;
    case 'select':
      return prop.select?.name ?? null;
    case 'multi_select':
      return prop.multi_select?.map((s: any) => s.name) ?? [];
    case 'date':
      return prop.date?.start ?? null;
    case 'checkbox':
      return prop.checkbox;
    case 'url':
      return prop.url;
    case 'email':
      return prop.email;
    case 'phone_number':
      return prop.phone_number;
    case 'people':
      return prop.people?.map((p: any) => p.name) ?? [];
    default:
      return null;
  }
}
```

### Step 3: Block Children, Pagination, Rate Limits, and More (Pitfalls #4-12)

```typescript
// PITFALL #4: Block children are NOT returned with page retrieval
// pages.retrieve() returns properties, NOT content blocks
// You need a SEPARATE call to get page content

// WRONG: expecting blocks from page retrieval
const page = await notion.pages.retrieve({ page_id: pageId });
// page.content — DOES NOT EXIST

// RIGHT: separate call for blocks
const blocks = await notion.blocks.children.list({ block_id: pageId });
// blocks.results contains the actual page content

// Also: nested blocks require recursive fetching (max 3 levels via API)
async function getAllBlocks(blockId: string): Promise<any[]> {
  const blocks: any[] = [];
  let cursor: string | undefined;

  do {
    const response = await notion.blocks.children.list({
      block_id: blockId,
      page_size: 100,
      start_cursor: cursor,
    });
    blocks.push(...response.results);
    cursor = response.has_more ? (response.next_cursor ?? undefined) : undefined;
  } while (cursor);

  // Fetch nested children (API max depth: 3)
  for (const block of blocks) {
    if ((block as any).has_children) {
      (block as any)._children = await getAllBlocks((block as any).id);
    }
  }

  return blocks;
}

// ---

// PITFALL #5: Pagination required for ALL list endpoints
// Every list endpoint returns max 100 results. ALWAYS check has_more.

// WRONG: only gets first 100 results
const response = await notion.databases.query({ database_id: dbId });
const allPages = response.results; // Missing results 101+!

// RIGHT: paginate through all results
async function queryAll(dbId: string, filter?: any): Promise<any[]> {
  const allResults: any[] = [];
  let cursor: string | undefined;

  do {
    const response = await notion.databases.query({
      database_id: dbId,
      filter,
      page_size: 100,
      start_cursor: cursor,
    });
    allResults.push(...response.results);
    cursor = response.has_more ? (response.next_cursor ?? undefined) : undefined;
  } while (cursor);

  return allResults;
}

// ---

// PITFALL #6: Rate limit is SHARED across all endpoints
// 3 req/s applies to ALL calls combined (queries + creates + updates + blocks)
// NOT 3/s per endpoint

// WRONG: separate throttles per operation type
// This uses 6 req/s total and will get 429 errors:
const readQueue = new PQueue({ interval: 333, intervalCap: 1 });   // 3/s
const writeQueue = new PQueue({ interval: 333, intervalCap: 1 });  // 3/s

// RIGHT: single shared queue for all operations
import PQueue from 'p-queue';
const notionQueue = new PQueue({
  concurrency: 1,
  interval: 340,      // ~3/s with margin
  intervalCap: 1,
});

// ALL calls go through this one queue
const queryResult = await notionQueue.add(() =>
  notion.databases.query({ database_id: dbId })
);
const createResult = await notionQueue.add(() =>
  notion.pages.create({ parent: { database_id: dbId }, properties: { /* ... */ } })
);

// ---

// PITFALL #7: Wrong property type in filter
// Each property type has its own filter syntax

// WRONG: using text filter on a select property
// { property: 'Status', text: { equals: 'Done' } }

// WRONG: missing the property type wrapper
// { property: 'Status', equals: 'Done' }

// RIGHT: match the filter type to the property type
const filterExamples = {
  title:        { prop