object_not_found on a page you can see
How you'll know: The ID is right and the page opens fine for you in the app.
Fix: The page isn't shared with your connection. Add it from the page's ••• menu under Add connections. Your own access doesn't count, because the token acts as the connection, not as you.
Database calls fail after someone edits the database
How you'll know: Creating pages in a database, or querying it, suddenly returns errors, and search stops finding it.
Fix: Since version 2025-09-03, a database is a container holding one or more data sources, each with its own schema. Older versions break once a database gets a second data source. Upgrade the version, look up the data_source_id by retrieving the database, and query with PATCH /v1/data_sources/{id}/query.
validation_error on a long description or a big import
How you'll know: Short test values work, real data doesn't.
Fix: Each rich text item holds at most 2,000 characters, a block array at most 100 elements, and a relation 100 pages per request. A payload tops out at 1,000 blocks and 500 KB. Split long text into several rich text items and append blocks in batches.
HTTP 429 during a backfill
How you'll know: The first few hundred calls work, then everything returns rate_limited.
Fix: Most plans get 180 requests a minute per connection, Business and Enterprise 600, and data source queries about three a second on top of a shared workspace budget. Read Retry-After (in seconds), back off, and pace the job instead of running it in parallel.
A property won't update
How you'll know: Writes to a formula, rollup, created time or last edited value are rejected.
Fix: Those are computed by Notion and read-only through the API. Write the inputs the formula or rollup depends on instead.