Notion API object_not_found (404): What to Check First
You try to read a page via the Notion API from a script, only to get an error saying it wasn't found. The ID was copied straight from the URL, and the token works on other pages. Yet for some reason, it returns a 404.
I hit this exact wall myself when I reused a token that was already working for a new purpose. Because it ran automatically, it quietly kept failing for days before I even noticed the error. This article outlines the troubleshooting checklist to follow when you get a 404.
What 404 (object_not_found) Means
According to the official Notion documentation, this error means that from the perspective of the token used, the resource does not exist. It also notes that this can indicate the resource has not been shared with the token's owner. The error message includes a line like this:
"code": "object_not_found",
"message": "… Make sure the relevant pages and databases are shared with your connection."In other words, 404 doesn't just mean "it doesn't exist"—it also means "it isn't visible to your API key." In practice, it's almost always the latter.
Steps to Check When You Get a 404
- 1. ConnectionDid you use "Add connections" on the page (or its parent)?
- 2. ID TypeDid you mistake it for a view ID or data source ID?
- 3. Original DatabaseDid you also share linked databases and relation targets?
The Most Common Cause: Missing "Add connections" on the Page
Simply creating an API integration (connection) does not grant it access to any pages. The official documentation explains that before an integration can interact with a page, that page must be manually shared with the integration.
You can share a page in the Notion UI as follows (per the Notion Help Center):
- Open the target page and click "•••" in the top right.
- Click "Add connections" near the bottom of the menu.
- Search for and select the integration you are using.
Adding a connection to a parent page grants access to all pages nested under it as well. The official documentation confirms that granting access to a parent page provides access to all of its child pages. If you keep related pages—like household task trackers—under a single parent page and add the connection only to that parent, you won't need to reconfigure settings every time you create a new page.
This is where I got stuck. Because I reused an existing token, I assumed everything was already set up. But the new target page was under a different parent page and didn't have the connection added.
Other Causes
| Cause | How to Check and Fix |
|---|---|
| Using a view ID | The value after "v=" in a database URL is the view ID, not the database ID. Use the 32 characters after the "/" and before the "?". |
| Confusing a database ID with a data source ID | In API version 2025-09-03 and later, databases and data sources have separate IDs. The official documentation explains that they cannot be used interchangeably. |
| Sharing a linked database | Sharing a database that is merely displayed on another page (a linked view) is not enough. Share the original database. |
| Related databases | To retrieve information from a database linked via a relation property, that target database must also be shared. |
To see which part of a URL is the ID, you can paste the URL into the Notion ID Finder. It clearly distinguishes page and database IDs from view IDs.
Differences from 401 and 403
Similar errors include 401 and 403. The official documentation explains them as follows:
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | The token is invalid (e.g., copied incorrectly or still using an outdated token). |
| 403 | restricted_resource | The token lacks required permissions, or the workspace has reached its block limit. |
| 404 | object_not_found | The resource does not exist from the token's perspective, or has not been shared. |
Troubleshooting is much faster if you remember the rule of thumb: check the token for 401, check integration permissions for 403, and check connections first for 404.
Preventing Silent Failures
In automated scripts, treating a 404 the same as "no data found" means failures can go unnoticed for days. I prevent this with two practices:
- Treat 404 as an error and halt execution. Distinguish it from "no matching results," and log the failure or record it on a separate Notion page.
- Run manually once when adding a new target. A missing connection is immediately obvious after a single manual run.
Summary
- 404 (object_not_found) means not just "does not exist," but also "has not been shared."
- First, check the "•••" menu on the page (or its parent page) → "Add connections". Adding it to a parent covers all descendant pages.
- Next, check whether you are confusing the ID with a view ID or data source ID, and verify that the original database and relation targets are also shared.
You can also interact with Notion from Claude Code using your own user permissions without an API token. See Connect Claude Code to Notion: Setting Up Notion MCP.