Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/notion-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-common-errors. Copyright stays with the author (MIT).

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

Read the JSON error body returned by the failed request.
Note its HTTP status and machine-readable code fields — those two values route you to the exact fix.
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 object_not_found — 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

Code	HTTP	Error Name	Retryable	Recommended Action
`unauthorized`	401	Authentication failure	No	Regenerate token at notion.so/my-integrations
`restricted_resource`	403	Missing capability	No	Enable capability in integration settings
`object_not_found`	404	Not shared / not found	No	Share page with integration via Connections menu
`validation_error`	400	Malformed request	No	Fix request body — retrieve schema first
`rate_limited`	429	Rate limit exceeded	Yes	Respect `Retry-After` header, use exponential backoff
`conflict_error`	409	Concurrent modification	Yes	Retry after 1-2s, serialize writes to same object
`internal_server_error`	500	Notion server error	Yes	Retry with backoff, check status.notion.so
`service_unavailable`	502/503	Notion down	Yes	Wait and retry, check status.notion.so
`gateway_timeout`	504	Request timeout	Yes	Retry, reduce query complexity or page size

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

Next Steps

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

notion-common-errors

About