communication api_limits ai_generated true

Notion API returns 400 error or silently truncates content when block has too much text

ID: communication/notion-api-rich-text-block-limit

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
3Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
any active — — —

Root Cause

Notion API limits rich text per block to 2000 characters. A single paragraph block cannot exceed this. The API either returns 400 or silently truncates. Also, page content is limited to 100 blocks per API call (pagination required).

generic

Workarounds

  1. 92% success Split text into 2000-character chunks across multiple paragraph blocks 
    chunks = [text[i:i+2000] for i in range(0, len(text), 2000)]; blocks = [{'paragraph': {'rich_text': [{'text': {'content': c}}]}} for c in chunks]
  2. 88% success Batch block appends in groups of 100 
    for i in range(0, len(blocks), 100): notion.blocks.children.append(page_id, children=blocks[i:i+100])
  3. 80% success Use Notion's toggle blocks for very long content to keep pages manageable 
    Wrap long content sections in toggle blocks. Each toggle can contain sub-blocks with their own 2000-char limits.

Dead Ends

Common approaches that don't work:

  1. Send a large text block assuming it will be stored as-is 88% fail

    Notion truncates at 2000 characters per rich text array element and 100 blocks per append call. Large documents are silently cut off.

  2. Append all blocks in a single API call 82% fail

    Maximum 100 blocks per append_block_children call. Documents with more blocks need paginated appends.