Notion Error Handlers

The Notion plugin includes built-in error handlers for common Notion API error scenarios.

Built-in Error Handlers

Rate Limit Errors

Triggers: HTTP 429 status

Behavior:

• Maximum retries: 5
• Respects Retry-After header

Example:

// Corsair handles rate limits automatically
const pages = await corsair.notion.api.databasePages.getManyDatabasePages({
    database_id: "database-id", 
});

Authentication Errors

Triggers: HTTP 401 status, invalid or revoked integration token

Behavior:

• Maximum retries: 0 (no retries)
• Fails immediately

How to Fix:

1. Verify your Notion integration token is valid
2. Ensure the integration has been shared with the target pages and databases
3. Re-create the integration token if it has been revoked

Permission Errors

Triggers: HTTP 403 status, integration not shared with resource

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Share the target page or database with your Notion integration
2. Verify the integration has the required capabilities enabled (read/write)

Not Found Errors

Triggers: HTTP 404 status, page or database does not exist

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Verify the page or database ID is correct
2. Check that the page has not been archived or deleted
3. Confirm the integration has access to the resource

Validation Errors

Triggers: HTTP 400 status, invalid property values or block types

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Check that property values match the database schema types
2. Verify block content follows the Notion block format
3. Ensure required fields are present

Network Errors

Triggers: Connection errors, timeouts

Behavior:

• Maximum retries: 3
• Uses exponential backoff

Custom Error Handlers

notion({
    errorHandlers: {
        MISSING_INTEGRATION_ACCESS: {
            match: (error) => {
                return error.message.includes("Could not find"); 
            },
            handler: async (error, context) => {
                console.log("Integration does not have access to this resource");
                return {
                    maxRetries: 0,
                };
            },
        },
    },
})

For comprehensive error handling strategies, patterns, and best practices, see the Error Handling concepts page.