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)
• NOTIONTOKEN 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.

Step 2: Match Error Code and Apply Fix

Use the Error Handling table below to see whether the error is retryable and the recommended action. For the exact error body, root cause, and copy-paste fix, open the matching section in references/error-codes.md. The four you will hit most:

• 404 objectnotfound — the most common error. The page/database exists but is not shared with your integration. Fix via the ... → Connections menu; parent pages must be shared too.
• 401 unauthorized — token missing, malformed, expired, or revoked. Verify with curl .../v1/users/me; regenerate at notion.so/my-integrations.
• 400 validation_error — the broadest category, usually a wrong property name/type or a filter-type mismatch (e.g. status: filter used as text:). Retrieve the database schema first.
• 429 rate_limited — over 3 requests/sec/integration. Back off exponentially; the SDK retries automatically.

Step 3: Verify the Fix

Re-run the failing call, or use the three-probe curl diagnostic in references/examples.md to confirm status, token, and resource access independently.

Output

• Identified error cause from HTTP status and code field
• Applied targeted fix from the matching section
• Verified resolution with test API call

Error Handling

Each row maps to a full walkthrough in references/error-codes.md.

Examples

Start with the fastest diagnostic — a single curl to confirm your token is valid and the integration is reachable:

curl -s https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" | jq '{id, type, name}'

A valid token returns your integration bot user. From there:

• Full three-probe diagnostic (status → token → database access): references/examples.md
• A single SDK catch block branching on every error code: references/examples.md
• Client-side shape gotchas that masquerade as validation_error (rich text arrays, block children, pagination, timeouts): references/examples.md

Resources

• Notion API Error Codes
• Request Limits & Rate Limiting
• Notion Status Page
• API Introduction
• Working with Databases
• @notionhq/client npm

Next Steps

For comprehensive debugging workflows, see notion-debug-bundle. For rate limit strategies at scale, see notion-rate-limits.