Agent Skills: 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:

{
  "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

{"object": "error", "status": 401, "code": "unauthorized", "message": "API token is invalid."}

Cause: Token is missing, malformed, expired, or revoked.

Fix:

# 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. Tokens starting with secret_ are legacy format — new integrations use ntn_ prefix.

403 — restricted_resource

{"object": "error", "status": 403, "code": "restricted_resource", "message": "Insufficient permissions for this resource."}

Cause: The integration exists and the page is shared, but the integration lacks the required capability (read content, update content, insert content, read comments).

Fix: Go to notion.so/my-integrations, select your integration, and enable the needed capabilities under "Capabilities." Common missing capability: "Read comments" when querying comments, or "Insert content" when creating pages.

404 — object_not_found

{"object": "error", "status": 404, "code": "object_not_found", "message": "Could not find page with ID: abc123..."}

Cause: The page, database, or block either does not exist or has not been shared with your integration. This is the single most common Notion API error.

Fix:

1. Open the target page in Notion
2. Click the ... menu at top right
3. Select Connections and add your integration
4. Parent pages must also be shared — sharing only a child page is not enough

// Defensive retrieval pattern
try {
  const page = await notion.pages.retrieve({ page_id: pageId });
} catch (error) {
  if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) {
    console.error('Page not shared with integration. Add via Connections menu.');
  }
}

Page ID gotcha: Notion URLs use 32-character hex IDs without dashes (https://notion.so/Page-abc123def456...). The API accepts both dashed (abc123de-f456-...) and undashed formats. If you're extracting IDs from URLs, strip the page title prefix and use the last 32 characters.

400 — validation_error

{"object": "error", "status": 400, "code": "validation_error", "message": "..."}

Message varies. This is the broadest error category. Common sub-cases:

| Message Pattern | Cause | Fix | |----------------|-------|-----| | Title is not a property that exists | Wrong property name | Use exact name from database schema (case-sensitive) | | ... should be an array | Rich text passed as string | Wrap in [{ text: { content: "value" } }] | | body.parent.database_id should be defined | Missing parent in page create | Include parent: { database_id: "..." } | | ... should be a string, instead was ... | Wrong property type for filter | Match filter type to property type (see below) | | Could not find property with name or id | Property renamed in Notion UI | Retrieve schema with databases.retrieve() to get current names |

Filter type mismatches — the most common validation error:

// WRONG: Status is a status property, not text
{ property: 'Status', text: { equals: 'Done' } }
// RIGHT: Use the matching filter type
{ property: 'Status', status: { equals: 'Done' } }

// WRONG: Passing plain string for title
{ Name: { title: 'My Page' } }
// RIGHT: Title requires rich text array
{ Name: { title: [{ text: { content: 'My Page' } }] } }

Debug tip: Always retrieve the database schema first to avoid property name/type errors:

const db = await notion.databases.retrieve({ database_id: dbId });
console.log(Object.entries(db.properties).map(([name, prop]) => `${name}: ${prop.type}`));
// Output: "Name: title", "Status: status", "Tags: multi_select", ...

429 — rate_limited

{"object": "error", "status": 429, "code": "rate_limited", "message": "Rate limited"}

Cause: Exceeded Notion's average rate limit of 3 requests per second per integration.

Fix:

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (isNotionClientError(error) && error.code === APIErrorCode.RateLimited) {
        const wait = Math.pow(2, attempt) * 1000; // exponential backoff
        console.log(`Rate limited. Waiting ${wait}ms (attempt ${attempt + 1}/${maxRetries})...`);
        await new Promise(r => setTimeout(r, wait));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

The @notionhq/client SDK has built-in retry with exponential backoff. If you hit rate limits frequently, batch operations and add delays between sequential calls. For bulk operations, see notion-rate-limits.

409 — conflict_error

{"object": "error", "status": 409, "code": "conflict_error", "message": "Transaction has an existing lock on the object."}

Cause: Concurrent modifications to the same page, block, or database. Common in parallel scripts or multi-user workflows.

Fix: Retry the operation. The SDK handles this automatically. If writing your own retry logic, a simple retry after 1-2 seconds resolves most conflicts. Avoid parallelizing writes to the same page.

500 — internal_server_error

{"object": "error", "status": 500, "code": "internal_server_error", "message": "Internal Server Error"}

Cause: Bug or transient failure on Notion's servers.

Fix: Retry with exponential backoff. If persistent (>5 minutes), check status.notion.so for ongoing incidents. Consider filing a bug report at developers.notion.com with the request ID from the response headers (x-request-id).

502/503 — service_unavailable

{"object": "error", "status": 503, "code": "service_unavailable", "message": "Notion is unavailable. Try again later."}

Cause: Notion's servers are down or under maintenance.

Fix:

# Check Notion status
curl -s https://status.notion.so/api/v2/status.json | jq '.status.description'

Wait and retry. Monitor status.notion.so for incident updates.

Step 3: Common Non-HTTP Gotchas

// "body failed validation: body.children should be an array"
// → Block children must always be an array, even for a single child.

// Rich text structure — the #1 source of frustration
// WRONG: "Hello"
// RIGHT: [{ type: "text", text: { content: "Hello" } }]
// Rich text is ALWAYS an array of rich text objects.

// Block type mismatch when appending children
// → Each block type has its own structure. A paragraph block needs:
//   { type: "paragraph", paragraph: { rich_text: [{ text: { content: "..." } }] } }

// Timeout errors (default 60s)
// → Increase via Client constructor:
//   new Client({ auth: token, timeoutMs: 120_000 })

// Pagination: missing results
// → Always check has_more and pass start_cursor for next page.
//   Notion returns max 100 items per request.

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 |

Examples

Full SDK Error Handler

import { Client, isNotionClientError, APIErrorCode, ClientErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

try {
  const page = await notion.pages.retrieve({ page_id: pageId });
} catch (error) {
  if (isNotionClientError(error)) {
    switch (error.code) {
      case APIErrorCode.ObjectNotFound:
        console.error('Page not found or not shared with integration');
        break;
      case APIErrorCode.Unauthorized:
        console.error('Invalid API token');
        break;
      case APIErrorCode.RestrictedResource:
        console.error('Integration lacks required capability');
        break;
      case APIErrorCode.RateLimited:
        console.error('Rate limited — retry with backoff');
        break;
      case APIErrorCode.ValidationError:
        console.error(`Validation error: ${error.message}`);
        break;
      case ClientErrorCode.RequestTimeout:
        console.error('Request timed out');
        break;
      default:
        console.error(`Notion error: ${error.code} — ${error.message}`);
    }
  } else {
    throw error; // Non-Notion error
  }
}

Quick Diagnostic Script

# 1. Check Notion status
curl -s https://status.notion.so/api/v2/status.json | jq '.status.description'

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

# 3. Test database access (replace DB_ID)
curl -s "https://api.notion.com/v1/databases/${DB_ID}" \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" | jq '{id, title: .title[0].plain_text}'

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.