notion-incident-runbook

# Notion Incident Runbook ## Overview Rapid incident response procedures for Notion API failures. This runbook covers a structured triage flow (under 5 minutes), automated health checks against both status.notion.so and your own integration, a decision tree for classifying failures (Notion-side vs. integration-side), per-error-type mitigation with real `Client` code, cached fallback patterns, communication templates, and postmortem structure. ## 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) Run this diagnostic script to determine if the issue is Notion-side or integration-side: ```bash #!/bin/bash # notion-triage.sh — run at first alert set -euo pipefail echo "=== Notion Incident Triage ===" echo "Time: $(date -u +%Y-%m-%dT%H:%M:%SZ)" # 1. Check Notion's public status page echo -e "\n--- Notion Platform Status ---" STATUS=$(curl -sf https://status.notion.so/api/v2/status.json \ | jq -r '.status.description' 2>/dev/null || echo "UNREACHABLE") echo "Notion Status: $STATUS" INCIDENTS=$(curl -sf https://status.notion.so/api/v2/incidents/unresolved.json \ | jq '.incidents | length' 2>/dev/null || echo "UNKNOWN") echo "Active Inc...