notion-common-errors

name	notion-common-errors
description	Diagnose and fix Notion API errors by HTTP status code and error code. Use when encountering Notion errors, debugging failed requests, or troubleshooting integration access, rate limiting, or validation issues. Trigger with phrases like "notion error", "fix notion", "notion not working", "debug notion", "notion 400", "notion 429".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

Notion Common Errors

Overview

Quick reference for all Notion API error codes with exact HTTP statuses, error bodies, and fixes. The API returns errors as JSON with three fields:

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Title is not a property that exists."
}

All requests require Authorization: Bearer $NOTION_TOKEN and Notion-Version: 2022-06-28 headers (2022-06-28 is the current stable API version — the header is required on every call).

This SKILL.md gives you the triage table and workflow. Two references carry the depth:

• references/error-codes.md — the full per-status playbook (401, 403, 404, 400, 429, 409, 500, 502/503) with error bodies, causes, and code fixes.
• references/examples.md — the full SDK error handler, the curl diagnostic script, and the non-HTTP client-side gotchas (rich text arrays, pagination, timeouts).

Prerequisites

• @notionhq/client installed (npm install @notionhq/client)
• NOTION_TOKEN environment variable set (internal integration token starting with ntn_ or secret_)
• Target pages/databases shared with the integration via the Connections menu

Instructions

Step 1: Identify the Error

1. Read the JSON error body returned by the failed request.
2. Note its HTTP status and machine-readable code fields — those two values route you to the exact fix.
3. If you only have logs, Grep your application logs for the code field to recover the values.