[Notion API][OAuth] page access와 capabilities가 맞지 않을 때 403 원인을 나누는 법

IT 리서치 노트

[Notion API][OAuth] page access와 capabilities가 맞지 않을 때 403 원인을 나누는 법

Notion OAuth를 붙인 뒤 토큰 교환까지는 됐는데 API가 403을 돌려주면 많은 팀이 곧바로 토큰이 죽었다고 생각한다. 하지만 2026년 6월 27일 기준 Notion 공식 문서를 다시 보면, 403 `restricted_resource`는 capability 문제일 수 있고, 404 `object_not_found`는 페이지가 연결에 공유되지 않은 상태일 수도 있다. 이 글은 page access와 capabilities가 어긋난 상황에서 403 원인을 어떻게 나눠 읽을지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Notion API의 403은 '토큰이 있다 vs 없다'의 문제가 아니라 '이 endpoint에 필요한 capability가 있는가'와 '해당 페이지가 이 연결에 실제로 공유됐는가'를 같이 봐야 풀린다. read 계열은 read content, write 계열은 update content capability가 먼저 갈리고, 공유가 안 된 페이지는 404 object_not_found로 보일 수 있다. 그래서 Notion 403 분석은 endpoint 종류와 공유 상태를 분리해서 보는 편이 가장 빠르다.

이미 redirect URI와 capabilities 글이 토큰 발급 전 단계를 다뤘다면, 이번 글은 토큰 발급 후 단계다. internal connection과 public OAuth 글까지 같이 보면 connection 타입과 권한 범위를 한 번에 정리할 수 있다.

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

현장에서 자주 꼬이는 지점은 세 가지다. 첫째, OAuth token exchange가 성공했으니 어떤 page든 읽을 수 있다고 생각한다. 둘째, retrieve page가 403인데 페이지 공유부터 확인하지 않고 endpoint capability를 놓친다. 셋째, read는 되는데 update block만 403인 상황에서 같은 권한 문제라고만 보고 write capability 차이를 놓친다.

Notion authorization 가이드는 authorization을 데이터 접근 권한 부여 과정으로 설명하고, capabilities 문서는 연결과 PAT가 어떤 endpoint와 데이터에 닿을 수 있는지 capability가 결정한다고 말한다. retrieve page 문서는 read content capability가 없으면 403을 반환한다고 적고, update block 문서는 update content capability가 없으면 403이라고 적는다. status code 표는 403 restricted_resource와 404 object_not_found를 별도 의미로 설명한다.

즉 같은 '접근 실패'여도 조치 순서가 다르다. 403이면 먼저 endpoint capability가 맞는지 보고, 404면 공유 상태와 connection 연결을 먼저 본다. 이 두 단계를 뒤섞으면 토큰을 새로 발급해도 같은 페이지에서 계속 막히거나, 페이지를 공유했는데도 write capability가 없어 여전히 403이 나는 식으로 시간이 길어진다.

• 증상: token exchange는 성공했는데 retrieve page가 403이다.
• 실패: OAuth 성공을 페이지 접근 성공과 같은 뜻으로 본다.
• 막힘: read와 update가 다른 capability를 요구한다는 점을 놓친다.
• 누락: 404 object_not_found를 공유 누락 신호로 읽지 않는다.

증상	먼저 볼 곳	판단 기준
retrieve page가 403	read content capability	이 endpoint가 읽기 권한을 요구하는지 본다
update block이 403	update content capability	write capability가 빠졌는지 본다
404 object_not_found	페이지 공유 상태	connection에 실제로 공유됐는지 본다

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

Notion 403 점검은 네 단계로 고정하면 빠르다. 먼저 실패한 endpoint가 read인지 write인지 나눈다. 다음으로 그 endpoint 문서에서 요구하는 capability를 확인한다. 세 번째로 같은 page나 database가 connection에 공유됐는지 확인한다. 마지막으로 에러 body의 code가 restricted_resource인지 object_not_found인지 분리해서 기록한다.

1. 실패 endpoint가 read인지 write인지 먼저 나눈다.
2. endpoint 문서에서 필요한 capability를 확인한다.
3. 페이지와 데이터베이스가 connection에 공유됐는지 다시 확인한다.
4. 에러 body의 code와 message를 로그에 남긴다.

점검 메모 예시

endpoint=retrieve-page
capability_needed=read_content
page_shared_with_connection=true
error_code=restricted_resource
next_action=check capability settings in developer portal

이 흐름으로 보면 같은 403이라도 대응이 갈린다. retrieve page 403이면 capability부터, update block 403이면 write capability부터, 404면 공유 상태부터 본다. 이 순서를 팀 문서에 넣어 두면 OAuth 연결 이슈를 토큰 재발급으로만 반복하는 일을 줄일 수 있다.

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

첫 화면은 Notion authorization 가이드다. 여기서는 연결이 어떤 데이터에 접근할지 허용을 받는 과정이라는 기본 정의를 다시 확인할 수 있다.

Notion은 authorization을 연결이나 토큰에 Notion 데이터 접근 권한을 부여하는 과정으로 설명한다.

즉 토큰을 발급받았다는 사실만으로 모든 페이지 접근이 보장되지는 않는다. 어떤 연결 타입인지, 어떤 워크스페이스와 페이지에 실제로 연결됐는지를 따로 봐야 한다.

두 번째 자료는 capabilities reference다. 여기서는 연결과 PAT가 각각 어떤 endpoint와 데이터에 닿을 수 있는지 capabilities로 제한된다고 적고 있다.

Notion capability 문서는 토큰이 호출할 수 있는 endpoint와 볼 수 있는 데이터 범위를 capability로 제한한다고 설명한다.

이 문장을 기준으로 보면 403 원인은 공유 누락만이 아니다. 토큰이 페이지에 연결돼 있어도 read content나 update content capability가 없으면 endpoint 수준에서 막힐 수 있다.

세 번째 화면은 retrieve page endpoint의 capability 요구사항이다. 이 endpoint는 read content capability가 없으면 403을 반환한다고 명시한다.

Retrieve a page endpoint는 read content capability가 없으면 403을 반환한다고 적고 있다.

즉 page ID가 맞아도 read content가 없으면 403이다. 반대로 capability는 맞아도 페이지가 연결에 공유되지 않았다면 404 계열로 보일 수 있다. 두 경우를 섞으면 디버깅이 길어진다.

네 번째 자료는 write 계열 endpoint 예시다. update block 문서는 update content capability가 없으면 403을 반환한다고 말한다.

write 계열 endpoint는 update content capability 누락 시 403을 반환한다.

이 차이를 알아야 read는 되는데 update만 403인 상황을 빨리 설명할 수 있다. 같은 토큰이어도 capability 세트가 다르면 endpoint별 성공과 실패가 갈린다.

다섯 번째 화면은 status codes 표다. 여기서는 403 `restricted_resource`와 404 `object_not_found`를 다르게 설명한다.

Notion status code 표는 403 permission 문제와 404 공유 또는 존재 문제를 분리해 설명한다.

특히 404는 리소스가 없다는 뜻만이 아니라 연결에 공유되지 않았다는 뜻일 수도 있다고 적혀 있다. 그래서 403과 404를 같은 페이지 접근 문제로 보더라도 조치 순서는 달라진다.

Notion 403은 endpoint 성격을 표로 정리해야 빨리 갈린다. read content, update content, 공유 상태를 같은 표에 두면 토큰은 살아 있는데 왜 막히는지 설명하기 쉽다.

Notion 403과 404를 capability와 공유 상태로 나누는 점검표다.

이미 redirect URI와 capabilities 글을 읽었다면, 이번 표는 토큰 발급 이후 단계에서 왜 막히는지로 읽으면 된다.

마지막 자료는 에러 응답 본문을 읽는 예시다. status code와 `code` 필드를 같이 보면 잘못된 토큰인지, capability 누락인지, 공유 문제인지 방향이 빨리 잡힌다.

Notion 에러 응답에서 `restricted_resource`와 `object_not_found`를 구분하는 예시다.

이 정도 메모를 로그에 남기면 403 재현 때 브라우저에서 연결 설정을 다시 열어 봐야 하는지, 페이지 공유부터 다시 해야 하는지 바로 갈린다. internal connection과 public OAuth 글과 같이 보면 connection 타입 판단도 더 빨라진다.

5. 주의사항과 리스크

첫 번째 리스크는 capability를 넓히는 것으로 모든 문제를 해결하려고 하는 것이다. 페이지가 공유되지 않았다면 capability를 넓혀도 404 계열이 계속 날 수 있다. 두 번째 리스크는 반대로 공유만 다시 하고 write capability를 놓쳐 read 성공 뒤 update 403이 반복되는 것이다. 세 번째 리스크는 error body를 저장하지 않아 403과 404를 나중에 구분하지 못하는 것이다.

운영 전에는 최소한 read endpoint 하나와 write endpoint 하나를 같은 연결로 테스트해 보고, 각각 어떤 capability가 필요한지 체크리스트를 남기는 편이 좋다. 그래야 실제 고객 워크스페이스에서 페이지가 안 보일 때 토큰 문제인지 공유 문제인지 더 빨리 자를 수 있다.

• OAuth 성공과 페이지 공유 성공을 같은 뜻으로 보지 않는다.
• read capability와 update capability를 별도로 점검한다.
• 403과 404의 error code를 로그에 남겨 다음 대응을 분리한다.

6. 결론

Notion API의 403은 대개 capability와 공유 상태를 한 덩어리로 본 데서 오래 끈다. endpoint가 요구하는 capability를 먼저 보고, 그다음 페이지가 connection에 실제로 공유됐는지 확인하면 restricted_resource와 object_not_found를 훨씬 빨리 나눌 수 있다. 이 분기만 정리해도 OAuth 이후 접근 장애 디버깅 시간이 크게 줄어든다.

• read와 write는 요구 capability가 다르다.
• 404는 공유 누락 신호일 수 있다.
• 에러 code를 남겨 capability 문제와 공유 문제를 분리한다.

7. 참고 링크

1. https://developers.notion.com/guides/get-started/authorization
2. https://developers.notion.com/reference/capabilities
3. https://developers.notion.com/reference/retrieve-a-page
4. https://developers.notion.com/reference/update-a-block
5. https://developers.notion.com/reference/status-codes