AIものさし

Notion APIの404 object_not_foundをID間違いと共有権限に切り分ける

Notion APIでpageやdatabaseを取得したとき、HTTP 404とobject_not_foundが返っても、ただちに「IDが間違っている」「対象が削除された」とは限りません。

AIものさし編集部

Notion APIでpageやdatabaseを取得したとき、HTTP 404とobject_not_foundが返っても、ただちに「IDが間違っている」「対象が削除された」とは限りません。Notionの現行Status codesは、指定resourceが存在しない場合に加え、Bearer tokenのownerへそのresourceが共有されていない場合も、この応答の理由になり得ると説明しています。つまり、IDを何度も作り直す前に、リクエスト先・ID・Connectionへの共有を別々に検査する必要があります。

この記事では、API応答から確認順を作り、resource管理者へ安全に共有依頼を渡すところまでを扱います。特定workspaceやIntegrationを操作した検証ではありません。workspaceの権限付与や実データの変更は、resourceを管理する人が行ってください。

目次

404を見たらresponse bodyから始める

Notion APIのerror responseでは、HTTP statusに加えてbodyのcodeとmessageが診断に使える情報です。まずstatusが404か、codeがobject_not_foundか、messageにpage/databaseのどちらが見つからないとあるかを保全します。messageにConnection名が含まれる場合は、そのConnectionが対象resourceへアクセスできない可能性を確認する手掛かりです。response本文が空、別のcode、別のstatusなら、この404手順だけを当てはめず、表示されたcodeに対応する公式Status codesを確認します。

Notionが示す主な違い：

・400 invalid_request_url / validation_error / missing_version：URL・request・schema・Notion-Version header等の確認。

・401 unauthorized：Bearer tokenが無効。resource共有よりtokenの有効性を確認。

・403 restricted_resource：tokenにpermissionがない、またはworkspace block limit。messageの理由を確認。

・404 object_not_found：resource不存在、またはBearer token ownerに未共有。

・429 rate_limited：request rateを落とし、公式の待機指示を確認。

・5xx：service側やtimeout等の別分岐。statusごとの現行説明に従う。

この区別は重要です。401ならAPI tokenの認証、403なら権限やworkspace block、404ならresourceの存在または共有範囲が論点になります。すべてを「権限不足」とまとめてConnectionを作り直すと、原因の違いを隠します。逆に、404をID typoだけとして扱い、共有設定を見落とすと、正しいIDを繰り返し貼っても解消しません。

リクエストが正しいか確認する

共有状態を変える前に、requestが期待するresourceを正しいendpointで読もうとしているかを確認します。ページ取得ならGET /v1/pages/{page_id}のpage ID、database等なら現在のNotion APIで該当するobjectとendpointを確認してください。NotionのAPIはversion headerを必須としており、現在の公式endpoint referenceに掲載されているNotion-Versionを使用します。古いblogや過去コードからheader値やdatabase endpointをそのままコピーせず、現行API Referenceでendpoint、object type、versionを確認してください。

確認項目：

・API hostとpathが現行のNotion API endpointか

・page ID、database ID、data source IDのどれを渡しているか

・UUIDを含むURLを渡す場合、ID部分を誤って切り出していないか

・前後の空白、余分なquery、URL encode/decodeミスがないか

・retrieve pageをdatabase/data source endpointへ送っていないか

・Notion-Version headerとBearer tokenが同一の想定環境に属しているか

・Integration/Connectionが期待するworkspaceにインストールされているか

IDをURLから取り出す場合、NotionページURLにはタイトル部分やquery stringが付くことがあります。アプリ側でそれら全部をIDとして送っていないか確認し、APIに渡している実値を機密情報のない形で記録します。IDの形式を整えることは有効ですが、見た目がUUIDらしいからresourceが存在すると証明できるわけではありません。Notionのページ取得APIが期待するのはpage IDであり、実際に存在するか・Connectionへ共有されているかは別途確認が必要です。

もし現在のconnectionに複数Integrationや複数workspaceがあるなら、実行中のBearer tokenがどのConnectionに対応しているかを確かめます。別の開発・本番tokenを取り違えると、正しいIDを指定していても、異なるworkspace ownerからresourceを探すことになります。secretをログに出さず、tokenの発行場所・環境名・管理者だけを照合してください。

resource共有を確かめる

IDとendpointが正しく見える場合、Notion側でAPI Connectionが対象resourceに共有されているかをresourceの所有者へ確認します。Notionの公式APIは、404がresourceをBearer token ownerへ共有していない場合にも生じると明記しています。Connectionがworkspaceに追加済みというだけで、すべてのpageやdatabaseが自動的に読めるとは判断しないでください。対象resourceまたは親ページの共有設定を、権限を持つ利用者が確認します。

共有確認では、次の情報をresource管理者へ渡します。

  1. 対象Connection名（API secret自体は送らない）

  2. 対象page/database/data sourceのタイトルと安全なURL

  3. リクエストに使ったendpointの種類とNotion-Version

  4. HTTP status、object_not_found code、機密を含まないmessage

  5. どのworkspace/environmentのConnectionを想定しているか

  6. Integrationに必要なread capabilityが有効かどうか

  7. pageが親page配下なら、共有階層を確認してほしい旨

NotionのRetrieve a page referenceでは、pageが見つからない場合だけでなくアクセスがない場合も404になり、read content capabilityが不足すれば403になると区別しています。また、page objectを取得できても、本文blockを読むには別のRetrieve block children操作が必要です。そのため、page metadataの取得成功だけで本文アクセスも許可されたと判断せず、実際の必要操作に応じて必要最小限のcapabilityと共有範囲を確認します。

resourceを所有する人が複数いる場合は、「Integrationがworkspaceに接続済み」という説明だけで完了にせず、対象page/databaseがどのConnectionへ共有されているかを確認してもらいます。組織の設定でIntegration追加が管理者承認制なら、利用者が私的なcopyを作ったり、別Connectionを増やしたりする前に、管理者の承認手順へ進みます。

databaseとpageを混同しない

NotionのAPIではpage、database、data sourceは別のobject・endpointとして扱われます。Notionの現在の資料では従来のDatabases APIがdeprecated扱いで案内され、新しいdata sourceの概念・endpointもあります。古いdatabase IDがあるからといって、現行のquery/retrieve方法が同じとは限りません。記事や実装時は取得したいobjectがdatabase containerなのか、その中のdata sourceなのか、個々のpageなのかを確認してからendpointを選びます。

ページのretrieveはpage objectとproperty valuesを返す処理で、page本文を読むにはblock childrenを取得するAPIが案内されています。databaseを表示するNotion URLを、常にpage IDやdata source IDとして利用できるとは限りません。画面上でdatabaseを開いている場所と、APIで問い合わせているobject IDを照合し、endpointとIDを組み合わせます。

Notion-Version headerも含めてrequestを再確認します。現行referenceがversionを必須としているため、headerが欠けているケースはversion-related 400の分岐になります。versionを足しただけで404が直るとは限りませんが、誤ったendpoint/versionの組み合わせがないかを先に除外できます。

安全な診断順序

  1. HTTP statusとbodyのcode/messageを正確に記録する。

  2. 401/403/404/429等を分け、404以外ならそのstatusの手順へ切り替える。

  3. endpointがpage、database、data sourceのどれを対象にしているか確認する。

  4. requestに渡すIDをAPI URLから切り出し、余計な文字や別objectのIDがないか確認する。

  5. Notion-Version header、Bearer token、environment、workspaceの取り違えを調べる。

  6. 404 object_not_foundなら、resource title/URLとConnection名をresource ownerへ渡し、共有状態を確認してもらう。

  7. 共有が必要なら、resource ownerまたはworkspace adminが対象Connectionへ必要なresourceだけ共有する。

  8. read-only retrieveを一度再実行し、status/bodyを記録する。本文が必要な場合はblock childrenの取得も別に確認する。

  9. なお404なら、ID、endpoint、resourceの移動・削除、Connection owner、workspaceを再照合し、request ID等の診断情報と一緒に管理者またはNotion supportへ進む。

同じrequestを短時間に繰り返すだけでは、resourceを共有する操作にはなりません。Notionが429を返したときはrate limitに従いrequest量を落とし、529ならRetry-After headerを尊重して後で再試行します。これらは404とは別の応答です。複数のエラーが混在する場合、直近の各responseを個別に記録し、成功したrequestだけを根拠に全体のアクセスが回復したとしないでください。

管理者へ渡す依頼テンプレート

件名：Notion API object_not_foundのresource共有確認

対象Connection名：

対象workspace / 環境：

対象resourceのタイトルとURL：

resource type（page / database / data source）：

API endpointとNotion-Version：

HTTP status / code：404 / object_not_found

message（secret等を除去）：

共有確認をお願いしたい点：対象resourceがこのConnectionのownerへ共有されているか、必要なread capabilityが有効か

API token、secret、Authorization header、顧客データを依頼文に含めないでください。ログを添付する場合も、Bearer tokenや個人情報が残っていないか確認します。

共有確認が通った後は、同じConnectionと同じ環境で、まず読み取り専用のretrieveを再試行します。権限付与後に404から200へ変わったか、response object IDが依頼したresourceと一致するかを確認します。page本文を読む作業ならblock children endpointも実行し、metadataだけ取得できた段階で作業を完了扱いしないようにします。

よくある誤判定

・404を「対象は削除済み」と即断する。未共有も同じobject_not_foundの理由になり得ます。

・404を必ず共有不足と決めつける。ID typo、resource不存在、別workspace、別token、別endpointも確認します。

・Connectionがworkspaceへ追加済みだから、すべてのpageが見えると考える。対象resourceへの共有を別に確認します。

・401と404を同じ権限問題にまとめる。401はtoken invalid、404はresource不存在または未共有という公式区分です。

・403と404を同一視する。Notionは403でpermission不足やworkspace blockを返し、404では未共有を含むnot-foundを示します。

・database、data source、pageのIDを同じAPI endpointへ渡す。

・page retrieve成功だけで本文blockも取得できると考える。

・token全体をログ・チャットに貼り、管理者に調査してもらう。

・共有後、IDやConnectionを確認せず、別のworkspace tokenで再試行する。

完了条件は、APIが200を返すことだけではありません。正しいresource、正しいConnection owner、承認された共有範囲、必要なread capability、正しいendpointとNotion-Versionを確認します。アクセスがない場合はresource管理者が最小範囲を共有し、API利用者は必要な読み取り操作だけ再試行します。未共有か不存在かをAPI利用者だけで確定できないときは、両方の可能性を残してownerへ確認を依頼します。

公式資料

Notion API｜Status codes

https://developers.notion.com/reference/status-codes（新しいタブで開く）

確認日：2026-10-15

Notion API｜Retrieve a page

https://developers.notion.com/reference/retrieve-a-page（新しいタブで開く）

確認日：2026-10-15

Notion API｜Retrieve a database

https://developers.notion.com/reference/retrieve-a-database（新しいタブで開く）

確認日：2026-10-15

Notion API｜Authorization

https://developers.notion.com/guides/get-started/authorization（新しいタブで開く）

確認日：2026-10-15