Notion Incident Runbook Skill

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

| Scenario | Triage Signal | Immediate Action | | ---------- | -------------- | ------------------ | | Notion platform outage | status.notion.so incident | Enable fallback mode, notify users | | Token expired/revoked | All requests return 401 | Rotate token in secret manager, restart | | Rate limited | 429 errors spiking | Reduce concurrency to 1, check for loops | | Schema changed | 400 on specific operations | Run databases.retrieve, update mappings | | Network/DNS issue | Timeouts, no HTTP response | Check firewall, DNS resolution, proxy config | | Pages unshared | 404 on previously working pages | Re-share via Connections menu in Notion |

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.

Agent Skills: Notion Incident Runbook

Install this agent skill to your local

Skill Files