I’m building a tool that converts webpage content into Notion pages using their API. Everything works fine until I hit the nested block depth limitation that Notion enforces.
The main problem happens when I try to create content structures like this:
Main section content
Bullet point list
Sub-item with details
Additional nested content (images or text)
The deepest level gets rejected by the API because it exceeds the maximum nesting depth. I know I can make a follow-up API call to add the deep content later, but finding the correct parent block ID becomes really tricky.
For instance, if I have multiple sub-items at level 3, how do I identify which specific one should be the parent for my level 4 content? The API returns IDs after block creation, but matching them back to the original structure is complex.
Has anyone dealt with this before? Looking for practical solutions that don’t involve completely restructuring the source content.
Hit this same problem building a doc importer last year. Skip trying to create everything at once - go breadth-first instead. I create blocks level by level and store each level’s IDs in arrays based on their original position. Need to add deeper content? Just reference the parent array using the child’s position index. Think of it as tree traversal, not complex ID mapping. Bonus: batching requests by depth actually speeds things up since you’re making fewer API calls. More planning upfront, but no more parent ID headaches.
same nightmare here with medium scraping. i fixed it by keeping a mapping dict during block creation - original content position as key, block id as value. when you hit the depth limit, just lookup the parent block id for your second api call. hacky but reliable.
Had this same problem migrating from Confluence. Here’s what worked for me: flatten everything first, then rebuild the hierarchy later. I give each content block a unique ID before sending to Notion, then run two passes. First pass creates all blocks at shallow levels that won’t break. Second pass moves the deeper stuff to where it actually belongs using the append children endpoint. Think of it like database normalization - split content creation from structure building. Takes more time but you don’t have to guess which parent blocks exist yet. Super helpful when you know ahead of time which sections will hit the depth limits.