노션 페이지에서 외부 서비스와 연동하려고 API 키를 입력했는데, 연동이 계속 실패하여 노션 API 확인 방법이 절실한 상황입니다. 복잡한 에러 메시지 없이 "유효하지 않은 요청"이라는 문구만 보고 멘탈이 나갔지만, 원인은 키 권한 설정이나 데이터베이스 식별자의 미세한 오타 때문이었습니다. 이 글에서는 실제 발생했던 구체적인 실패 사례 3가지를 분석하고, 터미널 명령어인 curl을 활용하여 정상 동작 여부를 판단하는 확실한 노션 API 확인 방법을 기술적으로 정리합니다.
- 401 Unauthorized 오류는 내부 통합 키의 권한 초대 여부를 의심해야 합니다.
- 404 Not Found 오류는 데이터베이스 ID를 잘못 가져왔을 때 발생하는 패턴입니다.
- curl 명령어를 사용해 헤더와 바디를 직접 전송하면 문제의 원인을 1분 안에 파악할 수 있습니다.
노션 API가 연결 안 될 때, 인증 토큰 확인부터 권한 설정, 요청 테스트까지 4단계로 빠르게 문제를 진단하고 해결할 수 있다.
사례 1: 401 Unauthorized 오류가 발생할 때의 노션 API 확인 방법
첫 번째 사례는 웹사이트의 문의 폼 데이터를 노션 데이터베이스로 전송하려던 개발자 A의 경우입니다. A는 노션 개발자 포털에서 '내 통합'을 생성하고 'Internal Integration Token'을 발급받아 코드에 붙여넣었습니다. 하지만 데이터를 전송할 때마다 서버 로그에는 401 Unauthorized 에러가 기록되었습니다. 이 오류는 클라이언트가 인증되지 않았음을 의미하며, 키가 잘못되었거나 권한이 없음을 나타냅니다.
A는 키를 여러 번 재발급받았지만 상황은 해결되지 않았습니다. 문제의 핵심은 키 자체의 유효성이 아니라, 해당 통합이 특정 데이터베이스에 대해 "작업"을 수행할 권한을 부여받지 못했다는 점이었습니다. 노션의 보안 정책상 키를 발급받는 것만으로는 충분하지 않으며, 실제 데이터가 저장될 페이지나 데이터베이스 설정에서 이 통합을 명시적으로 초대해야 합니다.
이 과정을 거치지 않으면 API 요청은 서버에 도달하지만 노션은 "누구냐"를 확인하고 요청을 거부합니다. 따라서 401 오류가 발생한다면 가장 먼저 데이터베이스 우측 상단의 ... 메뉴를 눌러 '연결된 항목' 목록에 생성한 통합이 포함되어 있는지 확인해야 합니다. 이것이 가장 기본적이면서도 간과하기 쉬운 노션 API 확인 방법의 첫 단계입니다.
통합 키는 절대로 깃허브 같은 공개 저장소에 올리거나 클라이언트 사이드 코드(자바스크립트 등)에 그대로 노출하면 안 됩니다. 키가 유출되면 타인이 당신의 노션 워크스페이스를 제어할 수 있게 됩니다.
Photo by Startup Stock Photos on Pexels
사례 2: 404 Not Found 오류로 연동 실패가 반복될 때
두 번째 사례는 자동화 도구를 사용해 노션 캘린더에 일정을 추가하려던 마케터 B의 경우입니다. B는 401 오류를 해결하고 통합을 데이터베이스에 성공적으로 연결했습니다. 하지만 이번에는 404 Not Found 오러가 발생했습니다. 이 오류는 주소가 잘못되었거나 리소스를 찾을 수 없을 때 반환됩니다. B는 워크스페이스의 URL을 확인하고 ID를 복사했다고 확신했습니다.
원인은 노션 페이지의 주소 구조에 대한 오해에서 비롯되었습니다. B는 브라우저 주소창에 표시된 긴 문자열 전체를 데이터베이스 ID로 사용했습니다. 하지만 노션 데이터베이스 ID는 URL의 특정 위치에 있는 32자리 영문과 숫자의 조합으로 구성된 고유값입니다. 주소창의 https://www.notion.so/워크스페이스이름/페이지이름-32자리ID?v=... 형식에서, 하이픈 뒤에 오고 물음표 앞에 오는 32자리 문자열이 정확한 ID입니다.
또 다른 경우는 페이지 ID와 데이터베이스 ID를 혼동했을 때 발생합니다. 사용자가 데이터베이스가 아닌 개별 페이지의 ID를 API 요청의 끝점으로 사용하면, 노션은 해당 페이지를 데이터베이스로 인식하지 못해 404 에러를 던집니다. 따라서 정확한 노션 API 확인 방법을 위해서는 요청을 보내기 전에 해당 ID가 실제 데이터베이스 리소스를 가리키는지 URL 구조를 면밀하게 검증하는 과정이 필수적입니다.
데이터베이스 ID를 찾는 가장 쉬운 방법은 데이터베이스 페이지를 연 뒤, 브라우저 주소창의 URL을 복사하는 것입니다. 하지만 API 요청 시에는 URL의 쿼리 파라미터(? 뒤의 내용)와 경로 이름을 제외하고 32자리 ID만 추출하여 사용해야 합니다.
사례 3: 400 Bad Request와 JSON 구조 오류 분석
동영상으로 보는 노션 API 확인 방법
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
세 번째 사례는 파이썬 스크립트를 작성하여 대량의 데이터를 한 번에 업로드하려던 데이터 분석가 C의 경우입니다. C는 인증과 ID 문제를 모두 해결했지만, 이번에는 400 Bad Request 오류를 마주했습니다. 이는 클라이언트의 요청 형식이 서버가 처리할 수 있는 규칙에 위배될 때 발생합니다. C는 자신이 보낸 데이터가 문제인지, 아니면 요청 방식이 문제인지 알 수 없어 당황했습니다.
원인은 API 버전 헤더와 요청 바디의 JSON 형식에 있었습니다. 노션 API는 기본적으로 최신 버전을 요구하며, 헤더에 Notion-Version을 명시하지 않거나 구버전을 사용하면 400 오류가 발생할 수 있습니다. 2024년 현재 안정적인 버전은 2022-06-28입니다. 또한, 데이터베이스에 새로운 페이지를 생성할 때 parent 객체에 반드시 database_id와 type을 올바르게 명시해야 합니다.
C의 경우 JSON 구조를 작성할 때 Q. Notion API 키가 제대로 동작하지 않을 때 확인해야 할 기본 사항은? A. 먼저 API 토큰에 공백이나 오타가 없는지 확인하고, 토큰이 최신 버전인지 검증합니다. 또한 토큰이 포함된 Authorization 헤더가 정확히 "Bearer Q. Integration이 올바른 페이지에 접근 권한을 가지고 있는지 어떻게 확인하나요? A. Notion 워크스페이스에서 해당 페이지를 열고, 오른쪽 상단의 "Share" 메뉴에서 Integration이 추가되어 있는지 확인합니다. 권한이 없으면 "Add people, groups, or integrations" 버튼으로 추가해 주세요. Q. API 요청이 401 Unauthorized 오류를 반환할 때 해결 방법은? A. 토큰이 만료됐거나 잘못된 경우가 대부분이니, 새 토큰을 발급받아 Authorization 헤더에 적용합니다. 또한 IP 제한이나 방화벽 설정이 API 호출을 차단하고 있지는 않은지도 점검해 보세요. Q. 최신 Notion API 문서와 버전 확인은 어디서 할 수 있나요? A. Notion 공식 개발자 포털(https://developers.notion.com)에서 최신 문서와 API 버전 정보를 확인할 수 있습니다. 변경 로그와 예제 코드는 해당 사이트의 "Release Notes" 섹션에 정리돼 있습니다.properties 내부의 속성 이름을 노션 스키마와 다르게 작성했거나, 필수 파라미터를 누락했습니다. 예를 들어, '제목' 속성은 노션 내부적으로
자주 묻는 질문
노션 API 확인 체크리스트
1 Notion Integration 페이지에서 Integration Token을 복사했는지 확인
2 터미널에서 curl -X GET "https://api.notion.com/v1/users/me" -H "Authorization: Bearer {TOKEN}" -H "Notion-Version: 2022-06-28" 로 토큰 유효성 검사
3 Notion Status 페이지에서 서비스 장애 여부 확인
4 요청 헤더에 Authorization와