Agent skill · data analytics · jeremylongshore
notion-common-errors
Classify Notion API failures and choose a bounded recovery path from the observed status and error code. Use when handling authentication, permission, validation, conflict, limit, or service errors. Trigger with "fix Notion error", "classify Notion 403", or "handle Notion 429".
Why this skill is useful
Provides a detailed error handling workflow for the Notion API, including specific error codes and resolutions that the AI wouldn't reliably generate on its own.
What it needs
Requires @notionhq/client installed locally. Requires notion account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Notion Error Classification and Recovery Overview Classify Notion API failures and choose a bounded recovery path from the observed status and error code.. This workflow produces an auditable decision or artifact before any live action. Prerequisites Current first-party Notion documentation and the selected integration's tested API-version contract. A named workspace owner, content or data owner, and operation owner. Synthetic or approved non-production fixtures with secrets and workspace content removed. Current Contract The response status, structured code, message, request identifier, and Retry-After header are evidence. Recovery differs for invalid credentials, restricted resources, wrong IDs, invalid payloads, conflicts, rate limits, and service faults. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Verify token presence through a fingerprint or secret-manager reference. Check connection capabilities and content sharing separately from identity. Instructions 1. Capture one redacted response envelope and the originating operation. 2. Map the status and structured code to authentication, authorization, validation, identity, concurrency, limit, or service class. 3. Check selected API version and page/database/data-source identity before changing code. 4. Apply the class-specific action: correct input, restore access, wait as instructed, reconcile conflict, or pause for service recovery. 5. Retry only retryable classes with a strict attempt and time budget. 6. Verify recovery with the least-privilege read or fixture that proves the original fault is gone. Tool Discipline Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/notion-common-errors