Notion Incident Runbook

Overview

Rapid incident response for Notion API failures. This runbook drives a sub-5-minute

triage that classifies the failure as Notion-side vs. integration-side, then routes to

per-error-type mitigation, cached fallback, and a structured postmortem.

Deep material — full triage scripts, remediation code, and templates — lives in

references/; this file is the high-level flow you follow live.

Prerequisites

• Access to application monitoring dashboards and log aggregator
• NOTION_TOKEN environment variable set for diagnostic API calls
• curl and jq installed for quick CLI triage
• Python alternative: notion-client (pip install notion-client)
• Communication channels configured (Slack webhook, PagerDuty, etc.)

Instructions

Step 1: Quick Triage (Under 5 Minutes)

At first alert, decide whether the fault is Notion's or yours. Check the platform

status page, then test your own auth. This one call is enough to start:

curl -sf -o /dev/null -w "%{http_code}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28"   # 2022-06-28 = pinned Notion API version

Map the result: 200 → integration-side, 401 → token expired/revoked, 429 →

rate limited, 000 → network/DNS. If status.notion.so shows an active incident, it

is Notion-side regardless of your auth code.

Read references/triage.md for the full notion-triage.sh

diagnostic (status page + auth + DB-query latency + auto-classification) and a

TypeScript triageNotionHealth() equivalent for in-app health checks.

Step 2: Decision Tree and Mitigation

Route the classification to a remediation path:

• Notion-side outage — enable cached/fallback mode, notify users, monitor the

status page. Do NOT restart or rotate tokens.

• 401 token expired/revoked — regenerate at notion.so/my-integrations, update the

secret manager, restart the app.

• 429 rate limited — you are exceeding the 3 req/s average; find runaway loops or

webhook storms, drop concurrency to 1, add exponential backoff.

• 404 on known resources — pages unshared or trashed; re-share via the Connections menu.
• 400 validation errors — the database schema changed in the UI; re-fetch with

databases.retrieve and update property mappings.

Read references/mitigation.md for the full decision tree,

token-rotation commands (AWS/GCP Secret Manager + kubectl restart), the

queryWithFallback() cached-fallback pattern, and detectSchemaChanges().

Step 3: Communication and Postmortem

Post an internal Slack update on every state change (INVESTIGATING → MITIGATING →

RESOLVED), an external status-page notice if users are impacted, and file a structured

postmortem once resolved. Copy-paste templates for all three are in

references/communication-and-postmortem.md.

Output

• Automated triage script classifying incidents in under 5 minutes
• Decision tree mapping HTTP status codes to root causes
• Per-error-type mitigation procedures with real code
• Cached fallback mode for Notion outages
• Schema change detection for 400 validation errors
• Communication templates for internal and external stakeholders
• Postmortem template with timeline and action items

Error Handling

Examples

One-Line Health Check

curl -sf https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" \
  | jq '{name: .name, type: .type}' \
  || echo "UNHEALTHY: Notion API unreachable or auth failed"

Python Quick Triage

from notion_client import Client, APIResponseError
import os

def quick_triage():
    try:
        client = Client(auth=os.environ["NOTION_TOKEN"], timeout_ms=10_000)
        me = client.users.me()
        print(f"OK: Connected as {me['name']}")
    except APIResponseError as e:
        print(f"ERROR: {e.code} (HTTP {e.status}): {e.message}")
    except Exception as e:
        print(f"NETWORK ERROR: {e}")

quick_triage()

For the full notion-triage.sh diagnostic and the TypeScript in-app variant, see

references/triage.md.

Resources

• Notion Status Page — real-time platform status
• Notion API Error Codes — full error reference
• Notion Request Limits — 3 req/s average
• Statuspage API — programmatic status checks
• For data handling and privacy compliance, see the notion-data-handling skill.