Notion API 401 오류 정리: "API token is invalid"와 "must use the format Bearer"는 뭐가 다를까
Notion API 401 "API token is invalid"와 "Authorization header must use the format Bearer"의 차이를 가짜 토큰으로 직접 재현하고 n8n 점검 순서를 정리했습니다.
n8n이나 curl로 Notion API를 호출했는데 401 "API token is invalid."가 나왔다면 토큰이 Notion에 도달했지만 받아들여지지 않았다는 뜻입니다. 그런데 같은 401이라도 "Authorization header must use the format \"Bearer <token>\""라는 다른 메시지가 있습니다. 가짜 토큰으로 읽기 전용 요청을 보내 두 메시지가 언제 나오는지 직접 확인했습니다. 진짜 토큰이나 워크스페이스는 쓰지 않았습니다.
두 가지 401 메시지
| 보낸 것 | HTTP | message | additional_data.reason |
|---|---|---|---|
Authorization 헤더 없음 | 401 | Authorization header must use the format "Bearer <token>". | 없음 |
Authorization: Bearer (토큰 값이 비어 있음) | 401 | 같은 "must use the format" 메시지 | 없음 |
Authorization: 토큰값 (Bearer 없이 토큰만) | 401 | 같은 "must use the format" 메시지 | 없음 |
Authorization: Bearer 가짜토큰 | 401 | API token is invalid. | token_invalid |
둘 다 code는 unauthorized입니다. 구분하는 방법은 메시지입니다. "must use the format"은 헤더 모양이 틀렸거나 비어 있다는 쪽이고, "API token is invalid"는 모양은 맞는데 토큰 값을 인정하지 않았다는 쪽으로 보였습니다.
직접 시험한 결과
2026년 11월 7일에 GET https://api.notion.com/v1/users/me로 보냈습니다. 모든 토큰은 지어낸 값입니다.
| 보낸 것 | 결과 |
|---|---|
헤더 없음 / 빈 Bearer / Bearer 없이 토큰만 | 401, "must use the format" |
가짜 secret_... 토큰 | 401, "API token is invalid.", token_invalid |
가짜 ntn_... 토큰 | 401, "API token is invalid.", token_invalid (secret_와 같음) |
가짜 토큰, Notion-Version 헤더 없음 | 401 "API token is invalid." (버전 오류가 아님) |
가짜 토큰, 말이 안 되는 버전 1999-01-01 | 401 "API token is invalid." (버전 오류가 아님) |
가짜 토큰, 없는 경로 /v1/nonexistent | 400, invalid_request_url, "Invalid request URL." |
- 가짜 토큰은 접두사가
secret_이든ntn_이든 같은 응답이었습니다. 응답만 보고 토큰 종류가 맞는지는 알 수 없습니다. 진짜 토큰이 없어 접두사별로 다른 동작이 있는지는 확인하지 못했습니다. - 토큰이 틀리면 헤더 오류보다 인증 오류가 먼저 나왔습니다. 공식 문서는
Notion-Version헤더가 없으면 400missing_version이라고 설명하지만, 제 시험에서 가짜 토큰에 버전 헤더를 빼면 400이 아니라 401이 나왔습니다. 토큰이 유효할 때 버전 오류가 어떻게 나오는지는 진짜 토큰이 없어 확인하지 못했습니다. 그러니 401을 고친 뒤에야 버전 오류가 나올 수 있습니다. - 없는 경로는 토큰과 상관없이 400이었습니다. 가짜 토큰을 붙여도 URL이 틀리면 401이 아니라 400
invalid_request_url이 나왔습니다. URL 오타가 있으면 토큰을 아무리 바꿔도 소용없습니다.
공식 문서가 설명하는 것
Notion 상태 코드 문서는 401 unauthorized를 "bearer token이 유효하지 않음"으로, 403 restricted_resource를 "토큰에 해당 리소스 권한이 없거나 워크스페이스 블록 한도를 넘음(원인은 오류 메시지에 적힘)"으로, 404 object_not_found를 "리소스가 없거나, 토큰의 연결(connection)에 공유되지 않은 경우일 수 있음"으로 설명합니다. 인증 문서는 토큰을 Authorization 헤더에 bearer 방식으로 보내라고 안내합니다.
n8n Notion 자격 증명 문서는 Notion의 Internal Integration Secret(통합의 Secrets 탭에 있는 Internal Integration Token)을 쓰고, 접근할 페이지마다 페이지 오른쪽 위 메뉴의 Connections에서 그 통합을 연결해야 한다고 설명합니다. 연결하지 않은 페이지에 대한 요청은 실패합니다.
점검 순서
- "must use the format": 토큰이 요청에 들어가지 않았거나
Bearer(뒤에 공백 한 칸)가 빠진 경우입니다. n8n HTTP Request 노드라면 인증 항목이 선택되어 있는지, 헤더 표현식이 빈 문자열이 되지 않는지 보세요. 시험에서 빈 Bearer와 접두어 없는 토큰이 이 메시지를 냈습니다. - "API token is invalid": 형식은 맞는데 값이 틀린 경우입니다. 토큰을 다시 복사하고 앞뒤 공백이나 줄바꿈이 없는지, 통합 화면에서 토큰을 다시 발급하지 않았는지 확인하세요. 제 시험은 가짜 토큰뿐이라 이 중 어느 원인이 어떤 메시지를 내는지는 구분하지 못했습니다.
- 401이 풀린 뒤 404가 나오면 토큰 문제가 아니라 공유 문제일 수 있습니다. 문서에 따라 해당 페이지나 데이터베이스에서 Connections로 통합을 연결하세요. 이 오류는 직접 재현하지 못했습니다.
- 403은 권한 문제로 문서가 설명합니다. 이것도 시험하지 않았으니 오류 메시지의 설명을 따르세요.
- URL부터 확인: 400
invalid_request_url은 토큰이 아니라 주소가 틀렸다는 뜻입니다.
비슷하게 "없음"과 "틀림"이 다른 메시지로 나오는 사례는 Stripe API 401 글(영어)과 GitHub API 401 글(영어)에도 정리했습니다.
시험하지 못한 것
- 진짜 Notion 토큰을 쓰지 않았습니다. 성공 응답, 403, 404(공유 안 됨), 토큰 재발급 후 오류는 확인하지 못했습니다.
GET /v1/users/me하나만 시험했습니다. 페이지, 데이터베이스 조회와 POST 요청은 시험하지 않았습니다.- n8n의 Notion 노드나 HTTP Request 노드 화면에서 어떻게 보이는지는 확인하지 않았습니다(curl로만 시험).
- OAuth 방식의 공개 통합(
invalid_grant등)은 다루지 않았습니다. - 하루 동안의 시험이고 Notion이 메시지를 바꿀 수 있습니다.
출처 Notion 상태 코드, Notion 인증, n8n Notion 자격 증명. 표의 결과는 제가 2026년 11월 7일에 보낸 요청의 결과입니다.
수정: 2026년 11월 7일