When you send an API request to Notion and receive an Invalid Page ID error, your integration cannot find the target page or database. This error appears in the API response body with a status code of 404. The root cause is almost always a mismatch between the ID you provide and the ID format Notion expects, or the integration lacking permission to access that resource. This article explains why the error occurs and provides step-by-step fixes to resolve it permanently.
Key Takeaways: Fixing the Invalid Page ID Error in Notion API
- Check the ID format: Notion API requires 32-character UUIDs with hyphens; a missing hyphen or extra character causes the error.
- Verify integration permissions: The integration must be added to the page or database via the Share menu before making API calls.
- Use the correct endpoint: Page IDs and database IDs are retrieved from the page URL or the Notion API’s search endpoint, not from the Notion app’s internal ID.
Why the Notion API Returns an Invalid Page ID Error
The Notion API uses UUID version 4 identifiers for pages, databases, and blocks. Every resource ID is a 32-character hexadecimal string displayed in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. When you pass an ID that does not match this pattern, the API rejects the request with an Invalid Page ID error.
There are three common scenarios that trigger this error:
1. Incorrect ID Format in the Request
The ID you copy from a Notion page URL may contain extra characters or be truncated. For example, the URL https://www.notion.so/My-Page-abc123def456... includes a title slug that is not part of the ID. You must extract only the 32-character UUID after the last slash and before any question mark.
2. Integration Not Shared With the Target Page
Even if the ID is correct, the API returns a 404 error if your integration has not been granted access to that specific page or database. Notion integrations must be explicitly added to each resource via the Share menu. This is a common oversight when testing with new pages.
3. Using a Block ID Instead of a Page ID
The Notion API distinguishes between page IDs, database IDs, and block IDs. If you pass a block ID to an endpoint expecting a page ID, the API returns an Invalid Page ID error. Block IDs are 32 characters as well, but they reference individual content blocks, not top-level pages.
Steps to Fix the Invalid Page ID Error
Follow these steps in order. Test your API call after each step to identify the exact cause.
- Verify the page ID format
Open the Notion page in your browser. Copy the URL from the address bar. The ID is the 32-character string after the last slash and before any question mark. It should look likeabc123def456abc123def456abc123de. Insert hyphens after every 8, 4, 4, and 4 characters:abc123de-f456-abc1-23de-f456abc123de. Use a UUID validator tool to confirm the format is correct. - Add your integration to the page
In the Notion app, open the target page. Click the Share button in the top-right corner. In the Invite field, type the name of your integration. Select it from the dropdown list. Click Invite. The integration now has access to this page and its children. - Check the endpoint URL in your API call
Ensure you are using the correct endpoint for the resource type. For a page, usehttps://api.notion.com/v1/pages/{page_id}. For a database, usehttps://api.notion.com/v1/databases/{database_id}. Do not use the blocks endpoint for page-level operations. - Retrieve the ID programmatically
Instead of copying the ID from the URL, use the Notion API’s Search endpoint to fetch the correct ID. Send a POST request tohttps://api.notion.com/v1/searchwith an empty body or a filter for page type. The response includes theidfield in the correct format. Copy this ID directly into your request. - Test with a simple GET request
Send a GET request tohttps://api.notion.com/v1/pages/{page_id}using the ID you retrieved. If the response returns page properties, the ID is correct and the integration has access. If you still get the error, double-check the integration token in the Authorization header.
If Notion Still Returns Invalid Page ID After the Fix
Integration Token Is Invalid or Expired
An expired or revoked integration token causes a 401 Unauthorized error, but some API clients may misinterpret this as an Invalid Page ID error. Generate a new token from the Notion Integrations page at https://www.notion.so/my-integrations. Update your API client with the new token and test again.
Page Is Inside a Private Teamspace
If the page resides in a private teamspace, the integration must be added to the teamspace itself. Open the teamspace settings, go to Settings & Members > Teamspaces, select the teamspace, click Add integrations, and add your integration. Then re-add the integration to the individual page as described in Step 2.
Database ID Used Where Page ID Is Expected
The Notion API uses separate endpoints for pages and databases. If you pass a database ID to the pages endpoint, you get the Invalid Page ID error. Confirm the resource type by checking the object field in the Search response. For a database, the object value is database, not page.
Notion Page ID vs Database ID vs Block ID: Key Differences
| Item | Page ID | Database ID | Block ID |
|---|---|---|---|
| Description | Identifies a single Notion page | Identifies a Notion database | Identifies a content block within a page |
| Endpoint | /v1/pages/{id} |
/v1/databases/{id} |
/v1/blocks/{id} |
| How to retrieve | Page URL or Search endpoint | Database URL or Search endpoint | Retrieve block children of a page |
| Error on wrong endpoint | Invalid Page ID | Invalid Database ID | Invalid Block ID |
You now know how to identify and fix the Invalid Page ID error in Notion API requests. Start by verifying the ID format and integration permissions on the target page. If the error persists, retrieve the ID programmatically using the Search endpoint and confirm you are using the correct endpoint for the resource type. As a final check, regenerate your integration token if it has expired or been revoked.