[Notion API][OAuth] 403 restricted_resource와 404 object_not_found를 실제 응답 기준으로 나누는 법

IT 리서치 노트

[Notion API][OAuth] 403 restricted_resource와 404 object_not_found를 실제 응답 기준으로 나누는 법

Notion OAuth를 붙인 뒤 접근 실패가 나면 403과 404가 비슷하게 보여 원인 분리가 자주 늦어진다. 2026년 7월 2일 기준 Notion 공식 문서를 다시 보면, 403 `restricted_resource`는 capability 부족 쪽 설명이 붙고, 404 `object_not_found`는 공유되지 않은 리소스나 잘못된 ID 쪽 설명이 붙는다. 이 글은 두 응답 코드를 실제 운영 기준으로 어떻게 갈라 볼지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Notion OAuth 접근 장애는 응답 코드부터 갈라야 한다. 403 restricted_resource가 나오면 endpoint가 요구하는 capability를 먼저 보고, 404 object_not_found가 나오면 page 또는 database sharing과 ID 형식을 먼저 봐야 한다. 이 둘을 같은 '권한 문제'로만 보면 capability를 넓혀도 404가 남고, 공유를 다시 열어도 403이 남는 상황이 반복된다.

이미 Notion 403 글과 Notion 404 글이 각각의 edge case를 다뤘다면, 오늘 글은 그 둘을 실제 응답 기준으로 묶는 비교형 허브다.

이번에 설치 토큰에서 page와 database 공유 범위를 나누는 글을 같이 보면, 왜 403과 404가 설치 설계 단계에서부터 갈리는지도 더 선명해진다.

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

현장에서 가장 자주 생기는 실수는 네 가지다. 첫째, token exchange 성공만 보고 page 접근도 자동으로 열렸다고 생각한다. 둘째, 403이 나와도 sharing부터 다시 열어 본다. 셋째, 404가 나와도 capability부터 넓힌다. 넷째, page와 database sharing을 같은 것으로 본다.

하지만 공식 문서는 이 둘을 다르게 설명한다. status code 표에서 403은 '이 operation을 수행할 permission이 없다'는 쪽이고, 404는 '리소스가 없거나 bearer token owner와 공유되지 않았다'는 쪽이다. retrieve endpoint 문서는 capability 부족이면 403이라고 적고, query database 문서는 공유되지 않은 database는 404라고 적는다.

즉 응답 코드가 곧 첫 번째 분기다. 403과 404를 한 덩어리로 보면 로그를 다시 읽어도 무엇부터 눌러 봐야 할지 정해지지 않는다. 반대로 응답 코드별로 'capability'와 'sharing/ID'를 먼저 보도록 고정하면 재시도 수가 크게 줄어든다.

• 증상: OAuth는 붙었는데 특정 endpoint만 실패한다.
• 실패: 403과 404를 같은 접근 실패로만 취급한다.
• 막힘: page sharing과 database sharing을 같은 항목으로만 본다.
• 누락: error body의 code와 message를 운영 로그에 남기지 않는다.

증상	먼저 볼 곳	판단 기준
retrieve endpoint가 403	endpoint capability 요구사항	read 또는 update content 부족인지 본다
retrieve/query가 404	page/database sharing과 ID 형식	공유 누락인지 ID 오타인지 구분한다
같은 token으로 page는 열리는데 query만 실패	원본 database 공유 상태	linked view가 아닌지까지 본다

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

운영 순서는 단순하게 고정하는 편이 낫다. 먼저 error body의 code를 기록한다. 403이면 endpoint 문서에서 요구 capability를 다시 보고, 404면 page 또는 database sharing을 UI에서 먼저 확인한다. 그다음 404는 URL에서 가져온 ID 형식까지 다시 본다. 마지막으로 같은 token으로 retrieve page와 query database를 각각 한 번씩 호출해 page 축과 database 축을 분리한다.

1. error body의 code와 message를 기록한다.
2. 403이면 endpoint capability를 먼저 확인한다.
3. 404면 page 또는 database sharing을 UI에서 다시 본다.
4. 404는 URL의 ID 형식도 함께 검증한다.
5. page 호출과 database 호출을 분리해 재현한다.

응답 기록 예시

endpoint=retrieve_page
status=403
code=restricted_resource
next_check=read content capability

endpoint=query_database
status=404
code=object_not_found
next_check=database sharing and page/database ID

이 방식이면 403과 404가 섞여 나오는 환경에서도 한 번에 두 문제를 섞지 않게 된다. 운영 문서와 CI 로그에 endpoint, code, next check를 함께 남겨 두면 다음 재현도 더 짧아진다.

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

첫 화면은 Notion status codes 표다. 여기서 403 `restricted_resource`와 404 `object_not_found`가 공식적으로 다른 의미라는 점을 먼저 확인해야 한다.

Notion status codes 표는 403 `restricted_resource`와 404 `object_not_found`를 별도 분기로 설명한다.

403은 권한과 capability 축에 가깝고, 404는 리소스 공유나 ID 축에 더 가깝다. 두 코드를 같은 '접근 실패'로만 묶으면 다음 조치 순서가 계속 흔들린다.

두 번째 자료는 read content capability가 없을 때 403이 나는 예시다. 실제 endpoint 문서를 보면 capability 부족은 403으로 드러난다는 점을 명확하게 보여 준다.

Notion endpoint 문서는 read content capability가 없으면 403을 반환한다고 안내한다.

즉 token exchange가 성공했더라도 connection capability가 endpoint 요구사항과 맞지 않으면 먼저 403부터 본다. 이 단계는 page sharing과는 다른 층위다.

세 번째 화면은 authorization 가이드다. 페이지가 connection에 공유되지 않으면 API 요청이 에러로 끝난다고 분명히 적고 있다.

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

이 문장은 404 분기를 이해할 때 중요하다. OAuth 토큰이 살아 있어도 특정 page나 database가 공유되지 않았다면 capability를 아무리 봐도 문제가 풀리지 않는다.

네 번째 자료는 database query endpoint 설명이다. 공유되지 않은 database는 404를 반환한다고 명시돼 있어, 404가 page ID 오타만을 뜻하지 않는다는 점을 다시 확인할 수 있다.

Query database endpoint는 공유되지 않은 database에 404를 반환한다고 적고 있다.

그래서 page는 열리는데 query만 실패할 때도 404 triage를 다시 써야 한다. page sharing과 database sharing이 같은 문제가 아니라는 뜻이다.

다섯 번째 화면은 page ID 형식 가이드다. 공유는 맞는데 URL에서 잘못된 ID를 잘못 복사해 오면 같은 404가 날 수 있으므로, 실제 형식 검증도 함께 봐야 한다.

Notion page content 가이드는 URL 끝의 page ID 형식을 예시와 함께 보여 준다.

이 단계가 빠지면 공유 문제로 오해하거나, 반대로 공유만 반복해서 열어 보게 된다. 404는 공유 상태와 ID 형식을 둘 다 확인해야 조치가 짧아진다.

마지막 자료는 응답 코드별 triage 표다. 403이면 capability와 endpoint 요구사항을 먼저 보고, 404면 sharing과 ID를 먼저 보는 방식으로 분기를 굳힌다.

403과 404를 실제 응답 기준으로 나누는 triage 표다.

이미 Notion 403 글과 Notion 404 글을 따로 읽었다면, 이 표는 둘을 하나의 운영 기준으로 묶는 허브 역할을 한다.

5. 주의사항과 리스크

첫 번째 리스크는 capability를 넓히면 404도 해결될 것이라고 믿는 것이다. 두 번째 리스크는 sharing만 다시 열면 403도 사라질 것이라고 생각하는 것이다. 세 번째 리스크는 database 쪽 404를 page ID 문제로만 몰아가는 것이다.

실무에서는 최소한 page retrieve 하나, database query 하나를 같은 connection으로 테스트해 두는 편이 좋다. 그래야 같은 OAuth 토큰 아래에서 capability 문제와 sharing 문제를 분리할 수 있다.

• 403은 capability 축이다.
• 404는 sharing 또는 ID 축이다.
• page와 database는 따로 재현해야 한다.

6. 결론

Notion OAuth 접근 장애를 빨리 줄이려면 403과 404를 실제 응답 코드 기준으로 먼저 갈라야 한다. 403은 endpoint capability를, 404는 sharing과 ID를 먼저 보도록 고정하면 같은 로그를 두 번 읽는 일이 줄어든다.

• 403은 capability부터 본다.
• 404는 sharing과 ID부터 본다.
• 둘을 섞지 않고 기록한다.

7. 참고 링크

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