Notion API breaking changes, updated weekly
Every verified Notion API trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all Notion API traps.
fg-0579· added 2026-10-30· last checked 2026-10-30
Notion markdown endpoint returns 400 validation_error when markdown_version is v1 on the next Notion-Version
Symptom
400 validation_error on POST /v1/pages, GET or PATCH /v1/pages/:page_id/markdown, POST /v1/comments or PATCH /v1/comments/:comment_id after bumping Notion-Version
Fix
Set markdown_version to v2 on all markdown requests now and test the parsed and written content. Stop sending v1 before you move to the new Notion-Version. Upgrade @notionhq/client to v5.29.0 or later for the parameter.
fg-0580· added 2026-10-30· last checked 2026-10-30
Notion MCP notion-ai-search is missing from tools/list and connector search needs notion-connector-search
Symptom
notion-ai-search no longer appears in the client tool list
Fix
Refresh the client's tool list or reconnect Notion MCP, then call notion-connector-search for Slack, Drive, GitHub, mail and calendar, optionally passing sources to narrow it. Use notion-fetch with a result id or url to open a connector result (Outlook, Google Calendar and Confluence results cannot be fetched).
fg-0553· added 2026-10-24· last checked 2026-10-24
Notion MCP notion-fetch returns notion-file-block:// references instead of downloadable file URLs
Symptom
page markdown from notion-fetch contains notion-file-block:// links
Fix
Pass include_file_urls: true to notion-fetch, or call notion-get-file-download-urls with up to 25 references. Keep the references, not the URLs, when editing or copying markdown.
fg-0555· added 2026-10-24· last checked 2026-10-24
Notion MCP notion-query-database-view returns a tool error saying to use notion-query-data-sources
Symptom
tool error naming notion-query-data-sources as the replacement
Fix
Call notion-query-data-sources with data.mode set to view and the same view_url.
fg-0556· added 2026-10-24· last checked 2026-10-24
Notion API returns validation_error for a custom_emoji icon that used to save and read back as null
Symptom
validation_error when setting a custom_emoji icon on a page, database, data source or callout
Fix
Use a custom emoji ID from the same workspace as the integration, or use a standard emoji or native icon.
fg-0559· added 2026-10-24· last checked 2026-10-24
Notion MCP notion-search no longer returns Slack, Drive or other connected-app results
Symptom
notion-search returns only Notion pages and databases
Fix
Call notion-connector-search for Slack, Drive, GitHub, mail and calendar. It only appears when the user has AI search and the workspace has a connected source. Refresh the client tool list or reconnect Notion MCP if it is missing.
fg-0554· added 2026-10-24· last checked 2026-10-24
Notion update_content batch fails with validation_error because one old_str is empty or matches nothing
Symptom
validation_error naming an old_str that wasn't found
Fix
Send only non-empty old_str values that exist on the page. Read the warnings array (codes no_match or indentation_mismatch) after each update, and re-fetch the page if a miss is reported.
fg-0540· added 2026-10-17· last checked 2026-10-17
Notion page markdown edit returns 400 validation_error on a very large page and retrying never works
Symptom
HTTP 400 validation_error when updating page content as markdown
Fix
Do not retry this 400. Retrieve the page as markdown and edit only content outside the tags, or split the page into smaller pages. Read additional_data.limit for the cap.
fg-0541· added 2026-10-17· last checked 2026-10-17
Notion page markdown write returns 504 gateway_timeout and the change may already be saved
Symptom
HTTP 504 gateway_timeout from Update a page's content as markdown
Fix
On 504, re-read the page and confirm whether the edit landed before retrying. Use additional_data.retry_guidance on 503. Update any error handling that matched only 500.
fg-0542· added 2026-10-17· last checked 2026-10-17
Notion 429 on one connection now means 600 or 180 requests per minute depending on plan
Symptom
429 rate_limited on a single integration at moderate sustained volume
Fix
Pace requests to the plan's per-minute budget, and honor Retry-After or additional_data.retry_after on 429 and 529. Check additional_data rate_limit_reason to tell a workspace limit from an endpoint limit.
fg-0546· added 2026-10-17· last checked 2026-10-17
Notion REST API returns 403 on a Free workspace once the block limit is reached
Symptom
HTTP 403 from page or block writes in an internal or selected-workspace OAuth connection
Fix
Reduce block count, upgrade the workspace plan, or review the grace period and background template behavior in the Workspace block limits docs. Treat this 403 as non-retryable.
fg-0454· added 2026-10-15· last checked 2026-10-15
Code that reads page.archived or passes after to append breaks after opting into Notion-Version 2026-03-11
Symptom
page.archived is undefined on every page
Fix
Update field names and block type checks before switching versions. In the JS SDK, upgrade to 5.12.0 or later and set notionVersion explicitly.
fg-0455· added 2026-10-15· last checked 2026-10-15
dataSources.query returns object_not_found when given the database ID copied from the Notion URL
Symptom
object_not_found from notion.dataSources.query with an ID taken from the page URL
Fix
Retrieve the database once with Notion-Version 2025-09-03, read data_sources[].id, and use that ID for queries and page parents. In the app, database settings > Manage data sources > Copy data source ID gives the same value.
fg-0464· added 2026-10-15· last checked 2026-10-15
Querying a large Notion data source stops at 10,000 rows with has_more false
Symptom
request_status.type: incomplete
Fix
Check request_status on every response, and split the read into windows (for example by created_time) that each stay under the cap. The JS SDK ships a helper that does this.
fg-0453· added 2026-10-15· last checked 2026-10-15
Appending more than 100 blocks or nesting three levels deep in one Notion request fails with validation_error
Symptom
body failed validation: body.children.length should be ≤ `100`
Fix
Send top-level blocks in batches of 100 and append deeper children in follow-up calls using the block IDs the first call returns.
fg-0456· added 2026-10-15· last checked 2026-10-15
Image and file URLs from the Notion API stop working about an hour after they are fetched
Symptom
AccessDenied: Request has expired when opening a stored Notion image URL
Fix
Download and rehost Notion-hosted files at build or sync time, or fetch the block again when expiry_time has passed. Never store the signed URL.
fg-0457· added 2026-10-15· last checked 2026-10-15
Integration on an older Notion-Version breaks once someone adds a second data source to a database
Symptom
validation_error when retrieving a database that worked the day before
Fix
Move the integration to Notion-Version 2025-09-03 or later and address data sources by ID. Page creation with a data_source_id parent works on every version, so switch that first.
fg-0458· added 2026-10-15· last checked 2026-10-15
Notion API returns 429 rate_limited during bulk imports at only a few requests per second
Symptom
429 rate_limited
Fix
Throttle to about 3 requests per second per connection, wait the Retry-After seconds on 429 and 529, and stop retrying when the reason is public_api_request_blocked.
fg-0459· added 2026-10-15· last checked 2026-10-15
Notion API returns object_not_found for a page or database that exists and opens fine in the app
Symptom
404 object_not_found
Fix
Connect the integration on the top-level page that holds everything it needs, then retry. Treat a 404 on a known ID as a sharing problem first.
fg-0460· added 2026-10-15· last checked 2026-10-15
Notion page response shows only 25 relations or people even though the property holds more
Symptom
Relation array stops at 25 entries
Fix
Read the full value through the page property item endpoint and page through every result.
fg-0461· added 2026-10-15· last checked 2026-10-15
Notion query or list call returns exactly 100 results and the rest are missing
Symptom
results.length is 100 and has_more is true
Fix
Loop on has_more and next_cursor, or use the SDK pagination helpers.
fg-0462· added 2026-10-15· last checked 2026-10-15
Notion rejects a paragraph or text property longer than 2000 characters with body failed validation
Symptom
400 validation_error
Fix
Split long strings into several rich text objects of at most 2000 characters. The rich_text array holds at most 100 items, so very long text needs several blocks.
fg-0463· added 2026-10-15· last checked 2026-10-15
Notion search filtered to object database stops matching after moving to API version 2025-09-03
Symptom
Search with filter value database no longer returns the databases it used to
Fix
Filter on data_source and group results by parent.database_id when you need one entry per database.
fg-0465· added 2026-10-15· last checked 2026-10-15
Retrying a Notion page create after a 502 or 503 leaves duplicate pages in the database
Symptom
Request to Notion API failed with status: 502
Fix
Before retrying a create, query for the row by a unique property you set on it. On 503, read additional_data.retry_guidance before deciding.
Have your agent check Notion API changes before it codes