Notion API가 대량 쓰기에서 429 rate_limited를 반환

안녕하세요, BlueByte입니다. Notion 페이지를 많이 만들거나 갱신하는 스크립트가 429로 실패하기 시작했다면, 뭔가 잘못한 게 아닙니다 — 그저 Notion이 받아줄 수 있는 속도보다 빠르게 보내고 있을 뿐입니다. 오늘은 응답이 무엇을 말하는지 읽고, 세 가지 방법으로 클라이언트 속도를 낮춰 오류를 멈추는 순서로 짚어보겠습니다.

Notion의 429가 뜻하는 것

대량 작업이 이렇게 실패합니다:

{ "object": "error", "status": 429, "code": "rate_limited",
  "message": "You have been rate limited." }

부하가 심하면 code service_overload의 529도 보일 수 있습니다. 코드 입장에선 둘 다 같은 뜻입니다 — 물러서라. 순수하게 속도 문제라, 페이로드나 토큰이 잘못됐을 때는 다른 오류가 나므로 그 둘은 건드릴 필요가 없습니다.

대량 쓰기가 한도를 이렇게 빨리 넘는 이유

Notion은 연동 하나당 평균 초당 3요청으로 제한하고, 짧은 순간의 버스트는 그 위로 허용합니다. 제한은 연결(연동 토큰) 단위라, 한 토큰으로 병렬로 쏘는 요청들은 하나의 예산을 나눠 씁니다 — 병렬이 처리량을 늘려주는 게 아니라 천장에 더 빨리 닿게 할 뿐입니다. 페이지 생성 루프나 수백 건에 대한 Promise.all이면 거의 즉시 걸립니다.

무언가 바꾸기 전에 응답부터 읽기

어떤 한도에 걸렸는지 추측하지 마세요 — 응답이 알려줍니다. 429에는 Retry-After 헤더(대기 초)와 additional_data.rate_limit_reason 필드가 실립니다:

curl -si -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" -H "Content-Type: application/json" \
  -d @page.json | grep -i "retry-after\|rate_limit_reason"

Retry-After가 있으면 속도 제한에 걸린 것입니다 — 토큰 오류(401)나 페이로드 오류(400)가 아닙니다. 이 헤더가 전혀 안 보이면 본문 전체를 로그로 남기세요. 거기 validation_error가 있으면 속도가 아니라 페이로드 문제입니다.

Retry-After를 지키고, 조절하고, 묶기

세 가지 변경을 싼 것부터 적용합니다.

1. Retry-After를 지킵니다. 429가 나면 딱 그만큼 자고 재시도하세요 — 절대 즉시 재시도하지 마세요.

async function notionFetch(url, options, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status === 429 && attempt < 5) {
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return notionFetch(url, options, attempt + 1);
  }
  return res;
}

2. 한도 아래로 조절합니다. 병렬 대신 ~350ms 간격으로 직렬 전송하세요. 초당 3요청 아래를 유지하면 429 자체를 거의 안 보게 됩니다.

3. 작업을 묶습니다. 한 요청으로 최대 100개의 블록 자식을 500KB 페이로드 안에서 추가할 수 있습니다 — 블록마다 요청하지 말고 한 번의 호출로 묶으세요.

실제 사례: 1,000행 임포트

행 하나가 블록 10개짜리 페이지인 1,000행을 임포트한다고 합시다. 순진하게 하면 생성 1,000번 + 추가 수천 번이라 몇 초 만에 429가 납니다. 재구성하면, 각 페이지를 블록 10개와 함께 한 요청으로 생성하고(100블록 천장 훨씬 아래) 그 생성들을 ~350ms 간격으로 직렬 전송합니다. 이제 초당 약 3페이지로 429 없이 돌아가고, 혹 하나가 새어 나가도 Retry-After 핸들러가 기다렸다 이어가므로 임포트가 실패하지 않습니다.

작업이 깨끗이 도는지 확인

돌려보며 상태 코드를 지켜보세요. 조절과 Retry-After가 자리 잡으면 대부분 200이 흐르고, 많아야 스스로 회복하는 429가 가끔 보일 뿐 — 재시도 안 된 429나 529는 없어야 합니다.

페이로드·인증 오류와의 구분

400 validation_error는 페이로드 문제(블록 과다, 한도 초과 필드)라 재시도해도 소용없습니다. 401 unauthorized는 토큰·공유 문제입니다. 오직 429/529만 속도 문제이고, 그 둘만 Retry-After를 싣습니다. 조절과 재시도를 공유 클라이언트 한 곳에 넣어 두면 앞으로 어떤 코드 경로도 이걸 우회할 수 없고, 다음 대량 작업은 그냥 됩니다.