[Notion API][OAuth] object_not_found가 날 때 page sharing 누락과 잘못된 page ID를 404 기준으로 나누는 법

IT 리서치 노트

[Notion API][OAuth] object_not_found가 날 때 page sharing 누락과 잘못된 page ID를 404 기준으로 나누는 법

Notion OAuth를 붙인 뒤 `object_not_found`가 뜨면 많은 팀이 잘못된 UUID부터 의심한다. 하지만 2026년 7월 1일 기준 Notion 공식 문서를 다시 보면, 404는 page나 database가 현재 connection에 공유되지 않았다는 뜻일 수도 있고, 잘못 자른 ID라는 뜻일 수도 있다. 이 글은 `object_not_found`를 page sharing 누락과 잘못된 page ID로 어떻게 나눠 볼지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 Notion의 object_not_found는 ID 오타와 공유 누락을 먼저 나눠 봐야 한다. status codes 문서는 404가 공유되지 않은 페이지나 데이터베이스를 뜻할 수도 있다고 적고 있고, authorization 가이드는 페이지가 공유되지 않으면 API 요청이 에러로 끝난다고 설명한다. 그래서 OAuth token exchange가 성공했더라도 page sharing과 page ID 형식을 따로 확인해야 404를 빨리 자를 수 있다.

이미 internal connection과 public OAuth 글이 connection 종류를 다뤘다면, 이번 글은 그 뒤의 실제 404 분기다. 또 403 capabilities 글을 봤다면 오늘은 capability보다 공유와 ID 형식을 먼저 보는 경우다. 403과 404를 한 화면에서 어떻게 나눌지 바로 보고 싶다면, 방금 정리한 403 restricted_resource와 404 object_not_found 비교 글을 같이 보면 분기가 더 빨리 잡힌다.

2. 어디서 실제로 막히는가

현장에서 가장 자주 겹치는 증상은 세 가지다. 첫째, OAuth 토큰이 잘 나왔으니 어느 페이지든 읽을 수 있다고 생각한다. 둘째, page URL에서 ID를 복사하면서 하이픈 위치를 틀리거나, 아예 다른 page의 링크를 가져온다. 셋째, page는 공유했는데 query 대상 database가 원본이 아니라 linked view라서 다시 404가 난다.

문제는 이 셋이 모두 비슷한 404처럼 보인다는 점이다. status codes 표는 공유되지 않은 리소스도 object_not_found로 설명하고, page content 가이드는 URL 끝 문자열을 올바른 page ID 형식으로 바꾸는 법을 별도로 적고 있다. query database endpoint도 공유되지 않은 database가 404라고 명시한다.

즉 object_not_found는 존재하지 않는 리소스 하나만 뜻하지 않는다. connection에 공유되지 않은 page, 잘못 자른 page ID, 접근 중인 database 자체가 다른 경우가 섞일 수 있다. 이걸 한 번에 UUID 문제로만 보면 공유를 다시 열어야 할 시점을 놓치고, 반대로 공유만 다시 하다 보면 잘못된 page ID를 계속 재시도하게 된다.

• 증상: token exchange는 성공했는데 retrieve page가 404다.
• 실패: 404를 곧바로 잘못된 UUID 하나로만 해석한다.
• 막힘: page와 database sharing을 같은 것으로 본다.
• 누락: URL 끝의 page ID 형식을 다시 검증하지 않는다.

증상	먼저 볼 곳	판단 기준
retrieve page가 404	page sharing과 page ID 형식	공유 여부와 하이픈 형식을 같이 본다
query database가 404	원본 database 공유 상태	linked database인지도 같이 본다
같은 토큰으로 다른 page는 열린다	문제 page의 Connections 메뉴	특정 page sharing 누락 가능성을 먼저 본다

3. 실무에서 적용하는 순서

404를 좁히는 순서는 네 단계면 충분하다. 먼저 해당 page나 database가 connection에 실제로 공유됐는지 UI에서 확인한다. 두 번째로 URL에서 가져온 ID를 8-4-4-4-12 형식으로 다시 검증한다. 세 번째로 page는 공유됐지만 database query가 404면 원본 database 공유 상태를 별도로 본다. 마지막으로 404 body에 connection 이름이 포함되는지 확인해 로그에 남긴다.

1. Connections 메뉴에서 공유 상태를 먼저 확인한다.
2. URL 끝의 page ID를 다시 형식 검증한다.
3. database query라면 원본 database 공유 상태를 따로 본다.
4. 404 body의 message와 connection 이름을 로그에 남긴다.

404 점검 메모 예시

resource_type=page
shared_with_connection=false
page_id_format_checked=true
query_target_is_original_database=true
error_code=object_not_found
next_action=share page in Connections menu

이 메모를 기준으로 보면 조치가 빠르게 갈린다. 공유가 false면 UI에서 page를 먼저 열고, 형식 검증이 false면 URL 값과 하이픈 형식을 다시 확인하고, database 원본 여부가 애매하면 linked view가 아닌지부터 본다. 404를 이 순서로 나누면 OAuth 이후 접근 장애를 훨씬 빨리 설명할 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 Notion status codes 표의 404 항목이다. 문서는 `object_not_found`가 단순히 리소스가 없다는 뜻만이 아니라, 관련 페이지나 데이터베이스가 현재 connection에 공유되지 않았다는 뜻일 수도 있다고 설명한다.

Notion status code 표는 `object_not_found`가 공유 누락 신호일 수도 있다고 적고 있다.

이 한 줄을 먼저 봐야 404를 잘못된 UUID 하나로만 해석하는 실수를 줄일 수 있다. 같은 404라도 ID 오타와 page sharing 누락은 조치 순서가 완전히 다르다.

두 번째 자료는 authorization 가이드다. 문서는 page를 connection에 직접 공유하지 않으면 API 요청이 에러로 끝난다고 분명히 적고 있다.

Notion authorization 가이드는 페이지가 공유되지 않으면 API 요청이 에러로 끝난다고 안내한다.

즉 token exchange가 성공했다고 곧바로 페이지 접근까지 열리는 것은 아니다. OAuth는 토큰 발급 단계이고, 특정 페이지 접근은 그 이후 공유 상태가 결정한다.

세 번째 화면은 내부 connection을 페이지에 붙이는 실제 UI 순서다. `•••` 메뉴에서 Connections를 열고 `+ Add connection`으로 연결을 추가하는 경로를 여기서 확인한다.

내부 connection은 페이지의 Connections 메뉴에서 직접 추가해야 접근이 열린다.

로그만 보고 404를 좁히기 어렵다면, 이 UI 경로를 실제로 다시 눌러 공유 상태를 확인하는 편이 빠르다. 공유가 빠진 상태에서는 capability를 넓혀도 같은 페이지가 계속 안 보일 수 있다.

네 번째 자료는 page ID를 어떻게 읽는지 설명하는 가이드다. 문서는 URL 끝의 32자 문자열을 8-4-4-4-12 형식으로 하이픈을 넣어 page ID로 사용하라고 안내한다.

Notion page content 가이드는 URL 끝의 page ID 형식을 예시와 함께 설명한다.

이 단계가 필요한 이유는 공유는 맞는데 ID를 잘못 추출해 404가 나는 경우를 구분하기 위해서다. 잘못된 UUID와 공유 누락은 같은 404로 보여도 바로 다음 액션이 다르다.

다섯 번째 화면은 database query endpoint의 permissions 설명이다. 공유되지 않은 데이터베이스를 query하면 404가 난다고 명시돼 있어, page뿐 아니라 database도 같은 패턴으로 본다는 점을 확인할 수 있다.

Query database endpoint는 공유되지 않은 데이터베이스에 404를 반환한다고 설명한다.

이 문장은 page 접근만 아니라 database 접근에서도 같은 triage를 써야 한다는 뜻이다. page는 공유돼 있는데 원본 database가 안 열려 있으면 query 단계에서 다시 404가 날 수 있다.

마지막 자료는 404 triage 표다. object_not_found가 났을 때 공유 누락인지, 잘못된 page ID인지, linked database 같은 다른 경계 문제인지 먼저 분리하는 데 쓴다.

Notion 404 triage 표는 page sharing 누락과 잘못된 ID를 같은 표에서 구분하게 만든다.

이미 redirect URI와 capabilities 글을 읽었다면, 이번 표는 token exchange 이후 단계의 404 점검표로 보면 된다. 또 403 capabilities 글과 함께 보면 capability와 sharing을 한 번에 분리할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 capability를 넓히면 404도 풀릴 것이라고 생각하는 것이다. page가 공유되지 않았다면 capability를 넓혀도 같은 404가 난다. 두 번째 리스크는 page는 공유했지만 query 대상 database가 원본이 아닌 linked view라서 다시 막히는 경우를 놓치는 것이다. 세 번째 리스크는 page ID를 복사하는 사람과 API 호출하는 사람이 달라 형식 오류가 생겼는데 로그에 남기지 않는 것이다.

운영 전에는 최소한 retrieve page 하나와 query database 하나를 같은 connection으로 테스트해 두는 편이 좋다. 그래야 같은 404라도 page sharing 문제인지, database sharing 문제인지, ID 형식 문제인지 분리해 둘 수 있다.

• 404는 공유 누락 신호일 수 있다.
• page와 database 공유는 별도로 확인한다.
• page ID 형식을 로그에 남겨 재시도를 줄인다.

6. 결론

Notion API에서 object_not_found가 났을 때는 잘못된 page ID와 page sharing 누락을 먼저 갈라 봐야 한다. status codes, authorization, page ID 가이드를 같이 보면 404를 단순 UUID 오류로만 보지 않게 되고, 공유 상태와 ID 형식을 각각 확인하는 순서를 만들 수 있다. 반대로 같은 OAuth 흐름에서 403과 404를 어떻게 갈라야 할지 헷갈릴 때는 403 restricted_resource와 404 object_not_found를 실제 응답 기준으로 나누는 글이 직접적인 후속 점검표가 된다.

• 공유를 먼저 본다.
• ID 형식을 다시 본다.
• page와 database를 따로 본다.

7. 참고 링크

1. https://developers.notion.com/reference/status-codes
2. https://developers.notion.com/guides/get-started/authorization
3. https://developers.notion.com/guides/get-started/internal-connections
4. https://developers.notion.com/guides/data-apis/working-with-page-content
5. https://developers.notion.com/reference/post-database-query