피드로 돌아가기
Dev.toBackend
원문 읽기
Notion API 10k Pagination Cap 도입에 따른 Silent Truncation 대응 전략
Notion's API Now Caps Pagination at 10,000 Results — Your 'Fetch All Rows' Sync Is Silently Truncating
AI 요약
Context
기존 Notion API는 has_more와 next_cursor 기반의 무제한 Pagination 계약을 유지함. 그러나 2026년 초부터 최대 10,000개의 결과 제한이 도입되며, 임계치 초과 시 에러 없이 200 OK와 함께 데이터가 절단되는 Silent Failure 구조로 변경됨.
Technical Solution
- request_status 필드 도입을 통한 응답 상태 정밀 검증 로직 구현
- has_more: false와 next_cursor: null 조건을 단순 종료 신호가 아닌 truncation 가능성으로 재정의
- incomplete_reason: query_result_limit_reached 값 확인을 통한 명시적 Exception Throwing 처리
- 대규모 데이터셋 확보를 위해 단일 쿼리 대신 Date Range나 Status 기반의 Query Partitioning 전략 채택
- API 응답의 구조적 유효성과 데이터의 완전성을 분리하여 검증하는 2단계 Validation 파이프라인 구축
실천 포인트
1. 모든 Pagination 루프 내에 request_status.type === 'incomplete' 체크 로직 추가
2. iteratePaginatedAPI 등 SDK 헬퍼 함수 사용 시 내부 필드 검증 여부 재확인
3. 10k 초과 예상 데이터셋에 대해 Property Range 기반의 쿼리 분할 설계 적용
4. 동기화 완료 후 실제 Notion 데이터 건수와 수신 건수를 대조하는 Cross-check 모니터링 구축