notion-common-errors

# 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: ```json { "object": "error", "status": 400, "code": "validation_error", "message": "Title is not a property that exists." } ``` All requests require `Authorization: Bearer <token>` and `Notion-Version: 2022-06-28` headers. ## 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 Run the diagnostic script below or check your application logs. Match the HTTP status and `code` field to the sections that follow. ### Step 2: Match Error Code and Apply Fix --- ### 401 — `unauthorized` ```json {"object": "error", "status": 401, "code": "unauthorized", "message": "API token is invalid."} ``` **Cause:** Token is missing, malformed, expired, or revoked. **Fix:** ```bash # Verify token is set echo ${NOTION_TOKEN:+SET} # Test directly curl -s https://api.notion.com/v1/users/me \ -H "Authorization: Bearer ${NOTION_TOKEN}" \ -H "Notion-Version: 2022-06-28" | jq . ``` If the response shows your integration bot user, the token is valid. Otherwise regenerate at [notion.so/my-integrations](https://www.notion.so/my-integrations). Tokens...