노션 API 로 사이트를 만들며 부딪힌 상한: 한 번에 보낼 수 있는 블록은 100개입니다

핵심 요약

• 이 블로그는 글을 노션 데이터베이스에 넣어두고 사이트를 만들 때 다시 읽어 옵니다. 그 과정을 붙이면서 걸린 노션 API 상한을 순서대로 적었습니다. 값은 2026년 8월 25일에 공식 문서에서 확인했습니다.
• 한 요청에 붙일 수 있는 자식 블록은 100개입니다. 글 한 편이 86개에서 123개 사이라 100개를 넘는 글은 잘라서 여러 번 보내야 했습니다.
• 텍스트 조각 하나의 상한은 2,000자입니다. 블록 단위가 아니라 조각 단위라, 긴 문단은 조각을 나눠 같은 블록에 넣으면 화면에는 한 문단으로 보입니다.
• 노션에 올린 이미지의 주소는 1시간이면 만료됩니다. 사이트에 그 주소를 그대로 쓰면 한 시간 뒤 깨지므로, 만들 때 내려받아 같이 배포하는 쪽으로 정했습니다.
• 우회할 수 없는 것도 있습니다. 표의 열 수는 표를 처음 만들 때만 정할 수 있고, 동기화 블록의 내용은 API 로 고칠 수 없습니다.

노션 API 로 사이트를 만들면 어디서 막히는가

노션을 글 저장소로 쓰고 사이트는 따로 만드는 구성은 흔합니다. 문제는 그 사이를 잇는 노션 API 에 상한이 여러 겹 걸려 있고, 그것들이 한꺼번에 보이지 않는다는 점입니다. 글이 짧을 때는 아무 일도 없다가 어느 순간 하나씩 튀어나옵니다.

저는 이 블로그를 그렇게 만들었습니다. 글은 마크다운으로 쓰고, 노션 데이터베이스에 올리고, 사이트를 만들 때 노션에서 다시 읽어 옵니다. 스물일곱 편을 올리는 동안 상한에 네 번 걸렸고, 걸릴 때마다 문서를 열어 값을 확인했습니다. 그 순서대로 적습니다.

요청 하나에 담을 수 있는 것

자식 블록 100개

블록을 붙이는 엔드포인트 문서에 이렇게 적혀 있습니다. "Arrays of block children longer than 100 will result in an error." 100개가 넘는 배열은 오류입니다.

이 블로그의 글 한 편은 노션 블록으로 86개에서 123개 사이입니다. 표 하나가 행 수만큼 자식 블록을 만들고, 불릿 목록도 항목마다 블록 하나이기 때문에 금방 100개를 넘습니다. 그래서 본문을 100개씩 잘라 여러 번 붙이는 코드를 넣었습니다. 최근에 올린 글 하나가 블록 86개였고 다른 하나가 123개였는데, 뒤엣것은 두 번에 나눠 갔습니다.

중첩에도 상한이 있습니다. 같은 문서에 "we allow up to two levels of nesting in a single request" 라고 적혀 있어서, 한 요청에서 두 단계까지만 중첩할 수 있습니다.

텍스트 조각 2,000자

요청 상한 문서의 표에 값이 항목별로 적혀 있습니다.

여기서 놓치기 쉬운 것이 2,000자의 단위입니다. 블록 하나가 2,000자가 아니라 텍스트 조각 하나가 2,000자입니다. 노션의 문단 블록은 서식이 다른 구간마다 조각이 나뉘는 구조라, 2,000자가 넘는 문단은 조각을 여러 개로 쪼개 같은 블록에 넣으면 통과합니다. 화면에는 한 문단으로 보입니다.

페이로드 1,000개와 500KB

같은 문서에 "payloads have a maximum size of 1000 block elements and 500KB overall" 이라고 적혀 있습니다. 앞의 100개 상한과 별개로 요청 하나의 전체 크기가 걸립니다. 이미지를 외부 주소로 참조하는 방식이면 500KB 에 잘 닿지 않지만, 본문에 긴 코드 블록이 여러 개 들어가면 계산해 두시는 편이 낫습니다.

요청 속도는 초당 3회

"an average of three requests per second, with some bursts beyond the average allowed" 라고 적혀 있습니다. 순간적으로 넘기는 것은 어느 정도 허용하지만 평균은 초당 3회입니다. 넘기면 HTTP 429 에 rate_limited 코드가 돌아옵니다.

워크스페이스 단위 한도는 그 워크스페이스의 모든 연결이 나눠 쓰고 요금제에 따라 조정된다고만 적혀 있습니다. 요금제별 숫자는 문서에 없습니다.

조회는 100건씩 끊깁니다

목록을 돌려주는 엔드포인트는 page_size 로 개수를 정하는데, 문서에 "Default: 100 Maximum: 100" 이라고 적혀 있습니다. 기본값도 100이고 최대값도 100입니다.

글이 100편을 넘으면 데이터베이스 조회 한 번으로는 전부 못 가져옵니다. 응답의 has_more 와 next_cursor 를 보고 다음 장을 이어서 요청해야 합니다. 지금은 글이 100편이 안 되어 한 번에 들어오지만, 넘기는 순간부터 나눠 받게 됩니다.

이미지 주소는 1시간이면 만료됩니다

파일 객체 문서에 이렇게 적혀 있습니다. "The URL is valid for one hour. If the link expires, send an API request to get an updated URL."

노션이 호스팅하는 파일은 file 타입이고 주소가 임시입니다. 외부에 이미 올라가 있는 파일을 가리키는 external 타입은 주소가 만료되지 않습니다. 프로그램으로 올린 파일을 가리키는 file_upload 타입도 있습니다.

이 한 줄 때문에 구조가 하나 정해집니다. 사이트를 독자 요청 시점에 노션을 읽는 방식으로 만들면, 노션에 올린 이미지는 한 시간 뒤 깨집니다. 그래서 이 블로그는 사이트를 만드는 시점에 노션을 읽고 이미지를 내려받아 사이트 파일과 함께 배포합니다. 이미지를 처음부터 외부 저장소에 두고 external 로 참조하는 방법도 있습니다.

만들 수 없는 블록과 고칠 수 없는 블록

블록 문서에 종류별로 제약이 흩어져 있습니다. 우회가 되는 것과 안 되는 것을 갈라서 정리했습니다.

표의 열 수 제약은 마크다운을 변환할 때 순서를 바꾸게 만듭니다. 머리글 줄을 먼저 읽어 열 수를 정하고 나서야 나머지 줄을 자식으로 붙일 수 있습니다. 줄마다 칸 수가 다른 표는 짧은 줄에 빈 칸을 채워 폭을 맞춰야 오류가 나지 않습니다.

API 버전 헤더는 빼먹으면 안 됩니다

버전 문서에 "The Notion-Version header must be included in all REST API requests" 라고 적혀 있습니다. 모든 요청에 넣어야 합니다. 버전 이름은 배포한 날짜이고, 문서에 적힌 최신 버전은 2026-03-11 입니다.

이 블로그는 아직 2022-06-28 을 씁니다. 버전을 박아두면 응답 모양이 바뀌어도 코드가 안 깨지는 대신 새 기능이 들어오지 않습니다. 어느 쪽을 고를지는 그 코드를 얼마나 자주 손볼 계획인지에 달렸습니다.

우회한 것과 설계로 피한 것

네 번 걸린 상한을 처리한 방식입니다.

넷 다 코드 몇 줄로 끝납니다. 그래서 "노션 API 는 제약이 많아 못 쓴다" 는 말은 이 네 가지에는 맞지 않습니다. 처음 한 번 처리해 두면 다시 볼 일이 없습니다.

문제가 되는 것은 앞 표의 우회 칸이 비어 있는 줄입니다. 표의 열 구성을 자주 바꾸는 콘텐츠라면 노션을 원본으로 두는 선택 자체를 다시 보셔야 합니다. 열을 바꿀 때마다 표를 지우고 다시 만들어야 하기 때문입니다.

확인하지 못한 것

• 429 응답에 `Retry-After` 헤더가 붙는지 확인하지 못했습니다. 상태 코드 문서는 529(서비스 과부하) 항목에서만 이 헤더를 언급하고 429 항목에는 언급이 없습니다. 실제로 429 를 받아본 적이 없어 응답 헤더를 직접 보지 못했습니다.
• 워크스페이스 단위 한도의 실제 숫자를 찾지 못했습니다. 문서는 요금제에 따라 조정된다고만 적고 값을 주지 않습니다.

실무 관점: 붙이기 전에 정할 것

1. 글 한 편이 블록 몇 개가 되는지 먼저 세어 보십시오. 표와 목록이 많으면 100개를 금방 넘습니다. 넘을 것 같으면 자르는 코드를 처음부터 넣는 편이 낫습니다.
2. 이미지를 어디에 둘지 먼저 정하십시오. 노션에 올릴 것인지 외부 저장소에 둘 것인지에 따라 사이트를 만드는 방식이 달라집니다. 노션에 올린다면 만드는 시점에 내려받아야 합니다.
3. 표의 열 구성을 자주 바꿀 계획인지 확인하십시오. 바꿀 계획이면 표를 노션 블록으로 옮기는 대신 다른 형태를 검토하십시오.
4. 버전 헤더를 어디에 둘지 정하십시오. 설정 파일 한 곳에 두면 나중에 올릴 때 한 줄만 고치면 됩니다.
5. 요청 속도를 초당 3회로 잡고 설계하십시오. 글 스물일곱 편을 한 번에 올리는 작업이라면 그 자체로 몇 분이 걸립니다.

자주 묻는 질문

노션을 CMS 로 써도 괜찮나요

이 블로그가 그렇게 돌아가고 있습니다. 다만 본문의 원본은 노션이 아니라 마크다운 파일로 두었습니다. 노션에서 고친 내용과 원본이 갈라지는 것을 막기 위해서입니다. 노션을 유일한 원본으로 쓰실 계획이면 표의 열 구성 제약을 먼저 확인하십시오.

무료 요금제로도 API 를 쓸 수 있나요

요청 속도 문서에 워크스페이스 한도가 "요금제에 따라 조정된다" 고 적혀 있고 요금제별 값은 나와 있지 않습니다. 통합 하나당 초당 평균 3회라는 값은 요금제 구분 없이 적혀 있습니다.

이미지가 깨지는 것을 막는 가장 간단한 방법은 무엇인가요

이미지를 외부 저장소에 올리고 노션에는 그 주소를 external 로 넣는 것입니다. 그러면 만료되지 않습니다. 노션 화면에서 직접 올리는 편이 편하다면, 사이트를 만드는 시점에 내려받아 함께 배포하시면 됩니다.

결론

노션 API 로 사이트를 만들 때 걸리는 상한은 네 개였고 순서가 있었습니다. 요청당 블록 100개, 텍스트 조각 2,000자, 조회 100건, 이미지 주소 1시간입니다. 넷 다 처음 한 번 처리하면 끝나는 항목이라 이것 때문에 노션을 포기하실 이유는 없습니다.

포기를 검토할 만한 것은 따로 있습니다. 표의 열 수를 나중에 못 바꾸는 것과 동기화 블록 내용을 API 로 못 고치는 것입니다. 이 둘은 우회가 없어서 설계 단계에서 피하는 수밖에 없습니다. 콘텐츠가 표 중심이라면 붙이기 전에 이 지점부터 확인하시기를 권장합니다.

모든 상한 값은 2026년 8월 25일에 노션 개발자 문서에서 직접 확인한 것입니다. API 문서는 버전과 함께 바뀌므로 붙이시기 전에 같은 주소를 다시 열어 확인하시기를 권장합니다.

관련 글

같은 방식으로 문서를 따라가며 확인한 기록입니다.

• 토스페이먼츠 연동을 문서대로 따라가봤습니다: 회원가입 없이 승인 API 까지 갑니다
• 헤드리스 CMS 무료 구간 비교: 무료 다음 계단이 35달러와 599달러로 갈립니다
• 정적 호스팅 무료 구간 비교: 셋이 애초에 서로 다른 것을 셉니다

---

출처

• Request limits (Notion API, 확인 2026-08-25)
• Append block children (Notion API, 확인 2026-08-25)
• File object (Notion API, 확인 2026-08-25)
• Block (Notion API, 확인 2026-08-25)
• Introduction (Notion API, 확인 2026-08-25)
• Versioning (Notion API, 확인 2026-08-25)
• Status codes (Notion API, 확인 2026-08-25)