Notion prod checklist

Notion API Production Deployment Checklist

Overview

A structured 12-section checklist for deploying Notion API integrations to production, covering authentication security, capability scoping, page sharing, rate limits, pagination, error handling, versioning, retries, monitoring, graceful degradation, data validation, and OAuth token lifecycle. Each section maps to a specific failure mode seen in production Notion integrations, and every item is testable — the skill produces a verified pass/fail report, not aspirational guidance.

Prerequisites

• Node.js 18+ with @notionhq/client v2.x installed
• Working Notion integration tested in a development workspace
• Production Notion API token (internal) or OAuth credentials (public integration)
• Target databases and pages identified by ID
• Deployment platform configured (Vercel, Railway, AWS, etc.)

Verify SDK is installed:

node -e "const { Client } = require('@notionhq/client'); console.log('SDK loaded')" 2>/dev/null \
  || echo "MISSING: npm install @notionhq/client"

Instructions

Work through the checklist in order, marking each item pass or fail. A single fail in sections 1-6 is a deployment blocker.

1. Run the pre-deploy smoke test (see Examples) to confirm the token is set, auth works, and target databases are reachable. This catches the most common failure — a page that is not shared with the integration — before you go deeper.
2. Grade each of the 12 sections against its checkbox items. The summary table below is the map; the full item-by-item detail, fail criteria, and code snippets live in references/checklist-sections.md.
3. Pull implementation patterns (rate-limited queue, paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange) from references/code-examples.md as each section requires them.
4. Record a pass/fail per section and total the blocking (1-6) vs non-blocking (7-12) failures.
5. Emit the readiness report (see Output) with the final verdict: ready to deploy, or blocked with the count of items to fix.

The 12 sections at a glance

#	Section	Blocking?	Fails if
1	Token in env vars (never hardcoded)	Yes	Token found in source, git history, or client bundle
2	Minimum required capabilities	Yes	Integration has scopes it does not use
3	Target pages/DBs shared with integration	Yes	Any target returns 404 object_not_found
4	Rate limit handling (3 req/sec, backoff)	Yes	Any path issues >3 concurrent requests unqueued
5	Pagination for all list endpoints	Yes	Any list endpoint skips the has_more loop
6	Error handling with isNotionClientError	Yes	Bare catch that loses error context
7	Notion-Version header pinned (2022-06-28)	No	Client created without explicit notionVersion
8	Retry logic for 429/500/503	No	Retries 400/401/404, or no retry on 429/5xx
9	Monitoring for API failures	No	No alerting on auth failures or sustained errors
10	Graceful degradation when Notion is down	No	Returns 500 to users when the API is unreachable
11	Data validation for property types	No	400 validation errors from unvalidated property data
12	OAuth token refresh (public integrations)	No	Tokens stored plaintext, or no 401 revocation handling

Full detail for every section — all checkbox items, capability/alert tables, and inline snippets — is in references/checklist-sections.md.

Output

After completing all 12 sections, produce a deployment readiness report:

NOTION PRODUCTION READINESS REPORT
===================================
Date: YYYY-MM-DD
Integration: [integration name]
Environment: [production|staging]

Section 1:  Token Security          [PASS/FAIL]
Section 2:  Capability Scoping      [PASS/FAIL]
Section 3:  Page/DB Sharing         [PASS/FAIL]
Section 4:  Rate Limit Handling     [PASS/FAIL]
Section 5:  Pagination              [PASS/FAIL]
Section 6:  Error Handling          [PASS/FAIL]
Section 7:  API Version Pinned     [PASS/FAIL]
Section 8:  Retry Logic             [PASS/FAIL]
Section 9:  Monitoring              [PASS/FAIL]
Section 10: Graceful Degradation    [PASS/FAIL]
Section 11: Data Validation         [PASS/FAIL]
Section 12: OAuth (if applicable)   [PASS/FAIL/N/A]

BLOCKING FAILURES (Sections 1-6): [count]
NON-BLOCKING ISSUES (Sections 7-12): [count]

VERDICT: [READY TO DEPLOY / BLOCKED — fix N items]

Error Handling

Scenario	Detection	Response
Token not in env vars	process.env.NOTION_TOKEN is undefined	Abort deploy, log setup instructions
Page not shared	404 object_not_found on retrieve	List unshared targets, block deploy
Rate limit exceeded	429 response despite queueing	Reduce concurrency, check for competing integrations
Validation error (400)	isNotionClientError with validation_error	Log full error body, fix property data
Auth failure (401)	isNotionClientError with unauthorized	Alert ops, rotate token, re-deploy
Notion outage (5xx)	Multiple 500/502/503 in sequence	Activate cache/fallback mode
Property type mismatch	400 on pages.create or pages.update	Run property validator, fix schema mapping
Pagination missed	Query returns exactly 100 results	Audit code for missing has_more loops

Examples

Pre-Deploy Smoke Test Script

Run this first — it validates the token, auth, and target-database access in seconds.

#!/usr/bin/env bash
set -euo pipefail

echo "=== Notion Production Smoke Test ==="

# 1. Token is set
if [ -z "${NOTION_TOKEN:-}" ]; then
  echo "FAIL: NOTION_TOKEN not set"
  exit 1
fi
echo "PASS: NOTION_TOKEN is set (${#NOTION_TOKEN} chars)"

# 2. Token works (auth check)
AUTH_RESULT=$(curl -s -w "\n%{http_code}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28")

HTTP_CODE=$(echo "$AUTH_RESULT" | tail -1)
BODY=$(echo "$AUTH_RESULT" | head -n -1)

if [ "$HTTP_CODE" = "200" ]; then
  BOT_NAME=$(echo "$BODY" | jq -r '.name // "unknown"')
  echo "PASS: Auth OK — bot name: $BOT_NAME"
else
  echo "FAIL: Auth returned HTTP $HTTP_CODE"
  echo "$BODY" | jq . 2>/dev/null || echo "$BODY"
  exit 1
fi

# 3. Target database accessible (set NOTION_TARGET_DB to test)
DB_ID="${NOTION_TARGET_DB:-}"
if [ -n "$DB_ID" ]; then
  DB_RESULT=$(curl -s -o /dev/null -w "%{http_code}" \
    "https://api.notion.com/v1/databases/${DB_ID}" \
    -H "Authorization: Bearer ${NOTION_TOKEN}" \
    -H "Notion-Version: 2022-06-28")

  if [ "$DB_RESULT" = "200" ]; then
    echo "PASS: Target database accessible"
  else
    echo "FAIL: Target database returned HTTP $DB_RESULT — is it shared with the integration?"
    exit 1
  fi
fi

echo "=== Smoke Test Complete ==="

Production Client Initialization

See full production initialization for complete setup with rate limiting, version pinning, and log levels. For the per-section snippets (paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange), see references/code-examples.md.

Resources

• Notion API Reference — Complete endpoint documentation
• Notion API Best Practices — Official key management guide
• Notion API Rate Limits — 3 req/sec per integration
• Notion API Changelog — Version differences and migration guides
• Notion Status Page — Real-time API availability
• @notionhq/client on npm — Official SDK documentation
• Notion OAuth Documentation — Public integration auth flow

Next Steps

After passing the production checklist, continue with related skills for ongoing operations. For initial setup and authentication, see notion-install-auth. For rate limit deep-dive, see notion-rate-limits. For error troubleshooting, see notion-common-errors. For incident response, see notion-incident-runbook. For API version migration, see notion-upgrade-migration. For monitoring setup, see notion-observability.