Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mark2notion.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the most common issues users encounter when using the Mark2Notion API. Each section includes the error message, what causes it, and how to fix it.

​
Table Conversion Issues

​
Table Cell Count Mismatch

Error: Number of cells in table row must match the table width of the parent table

Error Message:
Content creation Failed. Fix the following:
Number of cells in table row must match the table width of the parent table
What This Means: Your markdown table has rows with inconsistent numbers of columns. Notion requires all rows in a table to have the same number of cells.Common Causes:
  • Missing pipe separators (|) in markdown table rows
  • Extra or missing cells in some rows
  • Malformed table syntax with inconsistent column counts
  • Copy-pasted tables from other sources with formatting issues
Solutions:
  1. Check your markdown table syntax:
<!-- ❌ Bad: Inconsistent columns -->
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| A        | B        | C        |
| D        | E        |          <!-- Missing cell -->
| F        | G        | H        | I | <!-- Extra cell -->

<!-- ✅ Good: All rows have 3 columns -->
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| A        | B        | C        |
| D        | E        | F        |
| G        | H        | I        |
  1. Validate your table before sending:
    • Count the number of | separators in each row
    • Ensure header, separator, and all data rows have the same column count
    • Use a markdown editor with table validation
  2. Handle empty cells properly: 
<!-- Empty cells must still be included -->
| Name     | Email            | Phone |
|----------|------------------|-------|
| John     | john@example.com | 555-1234 |
| Jane     | jane@example.com |       |  <!-- Empty cell, but separator present -->
Working with AI-generated content? If you’re using AI tools (like ChatGPT, Claude, or other LLMs) to generate markdown, add this instruction to your prompt:“Ensure all markdown tables are properly formatted with an equal number of columns in each row.”This helps prevent table formatting errors before they reach the API.

​
Page and Block Access Issues

​
Invalid Page ID Format

Error Message:
path failed validation: path.page_id should be a valid uuid,
instead was "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
What This Means: The page ID you provided is not in the correct UUID format. Notion page IDs must be properly formatted UUIDs with hyphens.Common Causes:
  • Copying page ID from URL without hyphens
  • Using the page title or slug instead of ID
  • Including quotes or extra characters around the ID
  • Passing "null" or "<string>" as the page ID
Solutions:
  1. Easiest: pass the full Notion page URL — the API normalizes it automatically:
"pageId": "https://notion.so/My-Page-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
  1. Or pass just the page ID (with or without hyphens):
    • Copy the 32-character ID from the end of the page URL
    • Example with hyphens: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p
    • Example without hyphens: 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
  2. Don’t use these as page IDs:
    • ❌ Page titles: "My-Multi-Category-Document"
    • ❌ Literal strings: "null", "<string>"

​
Page or Block Not Found

Error Message:
Could not find page with ID: 12345678-1234-1234-1234-123456789abc.
Make sure the relevant pages and databases are shared with your integration.
What This Means: Your Notion integration doesn’t have access to the page, or the page doesn’t exist.Common Causes:
  • Page not shared with your integration
  • Page was deleted or moved
  • Using an old/expired page ID
  • Wrong workspace (integration in different workspace than page)
  • Page is in a private database
Solutions:
  1. Check your Notion connection in the dashboard:
    • Make sure your Notion workspace is connected via OAuth
    • The connected account must have access to the target page or its parent page/database
    • Try reconnecting if you recently moved or restructured pages
  2. Verify the page exists:
    • Try opening the page URL in your browser
    • Check if the page was recently deleted or archived
    • Confirm you’re in the correct workspace
  3. If using a manual notionToken:
    • Share the page with your integration via ··· → Connections → Add connection
    • For pages in databases, share the entire database — individual pages inherit access
  4. Check integration permissions:
If you just shared a page with your integration, wait a few seconds before making API requests. Notion may need a moment to propagate permissions.

​
Block ID Used Instead of Page ID

Error Message:
Provided ID abcd1234-5678-90ef-abcd-ef1234567890 is a block, not a page.
Use the retrieve block API instead
What This Means: You’re trying to use a block ID in the pageId parameter. All endpoints require a page ID, not a block ID.Solutions:
  1. Use the parent page ID:
    • Get the ID of the page that contains the block
    • The page ID is in the URL when you open the page
    • Use this page ID in the pageId parameter
  2. Want to insert after a specific block?
    • Use the page ID in the pageId parameter
    • Pass the block ID in the after parameter
    Example: 
    {
  "pageId": "https://notion.so/My-Page-12345678123412341234123456789abc",
  "after": "abcd1234-5678-90ef-abcd-ef1234567890",
  "markdown": "# Your content"
}
  3. Identify the difference: 
// Page URL - use this ID for pageId parameter
https://notion.so/My-Page-abcd12345678901234567890abcdef123456

// Block URL (notice the #) - use page ID for pageId, block ID for "after"
https://notion.so/My-Page-abcd12345678901234567890abcdef123456#block123...

​
Database ID Used Instead of Page ID

Error Message:
Provided ID aaaa1111-2222-3333-4444-bbbbccccdddd is a database, not a page.
Use the retrieve database API instead.
What This Means: You’re trying to add content directly to a database. You need to create or update pages within the database instead.Solutions:
  1. Create a page in the database first:
    • You cannot append content directly to a database
    • Create a new page in the database, then append to that page
    • Or get the ID of an existing page in the database
  2. Get a page ID from the database:
    • Open a page within the database
    • Copy that page’s ID from the URL
    • Use that page ID for your API request

​
Archived Block Access

Error Message:
Can't edit block that is archived. You must unarchive the block before editing.
What This Means: The page or block you’re trying to modify has been archived in Notion.Solutions:
  1. Unarchive the page/block:
    • Open the page in Notion
    • Click “Restore”
  2. Check page status before editing:
    • Verify the page is not in the trash
    • Ensure the parent page/database is not archived

​
Notion API Limitations

Good News: The Mark2Notion API now automatically handles all Notion API content limitations. The errors listed below should no longer occur, as our system automatically splits or truncates content to meet Notion’s requirements.If you encounter any of these errors, please contact support.

​
Rich Text Length Exceeded

Error Message:
body failed validation: body.children[0].paragraph.rich_text.length should be ≤ 100,
instead was 107
Status: This issue is now automatically handled by the APIWhat This Means: Notion limits rich text arrays to 100 elements per block. Blocks exceeding this limit are automatically split into multiple blocks.
This issue has been fixed. If you’re still seeing this error, please contact support at hello@mark2notion.com.

​
Text Content Length Exceeded

Error Message:
body failed validation: body.children[0].paragraph.rich_text[0].text.content.length
should be ≤ 2000, instead was 8039
What This Means: Individual text segments in Notion cannot exceed 2,000 characters.
This issue was fixed. The API now automatically handles text splitting.If you’re still seeing this error, it may indicate an issue with your Notion integration token. Please contact support.

​
Request Validation Errors

​
Missing Required Fields

Error Messages:
{"markdown": "Markdown is required"}
{"pageId": "Page ID is required"}
{"blocks": "Blocks must be a non-empty array"}
What This Means: Your request is missing required parameters.Solutions:
  1. Check required fields per endpoint:
  2. Common mistakes:
    • ❌ Sending empty strings: markdown: ""
    • ❌ Wrong data types: pageId: 123 (should be string)
    • ❌ Empty arrays: blocks: []
    • ❌ Undefined/null values: pageId: null

​
Empty or Invalid Markdown

Error Messages:
{"markdown": "Markdown cannot be empty"}
{"markdown": "No blocks generated from markdown"}
What This Means: Your markdown content is empty or doesn’t contain any valid content that can be converted to Notion blocks.Solutions:
  1. Ensure non-empty content:
    • Markdown must contain actual text content, not just whitespace or newlines
    • Check that your markdown string is not empty before sending
  2. Common invalid content:
    • ❌ Empty strings: ""
    • ❌ Only whitespace: " "
    • ❌ Only newlines: "\n\n\n"
    • ✅ Valid: "# Hello World" or any text with letters/numbers
  3. Validate before sending:
    • Trim whitespace and check if the result has actual content
    • Ensure the markdown contains at least some alphanumeric characters

​
Invalid JSON in Request

Error Messages:
Invalid JSON
Failed to parse request JSON. Bad control character in string literal...
Expected double-quoted property name in JSON at position X
Unexpected token 'm', "markdown=%"... is not valid JSON
What This Means: Your request body contains malformed JSON that cannot be parsed.Common Causes:
  • Unescaped special characters in strings (newlines, quotes, backslashes)
  • Form-encoded data instead of JSON
  • Syntax errors (missing commas, brackets, quotes)
  • Incorrect Content-Type header
Solutions:
  1. Use proper JSON encoding:
// ✅ Good: Properly escaped
const body = JSON.stringify({
  markdown: "Line 1\nLine 2\n\"Quoted\"",
  pageId: "2c785200-4c6e-8182-ab77-dbbadb4daed6"
});

// ❌ Bad: Literal newlines and quotes
const body = '{
  "markdown": "Line 1
  Line 2
  "Quoted"",
  "pageId": "xxx"
}';
  1. Set correct Content-Type header:
fetch('/api/append', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',  // Important!
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    markdown: content,
    pageId: pageId
  })
});
  1. Don’t use form encoding:
// ❌ Bad: Form-encoded
const body = 'markdown=' + encodeURIComponent(content);

// ✅ Good: JSON
const body = JSON.stringify({ markdown: content });
  1. Escape special characters:
// All special characters are automatically escaped by JSON.stringify
const markdown = `Content with "quotes", newlines\n, and \\ backslashes`;
const body = JSON.stringify({ markdown }); // Handles escaping

​
Authentication Issues

​
Invalid API Token

Error Message:
API token is invalid.
What This Means: The Notion integration token is invalid or has been revoked.Solutions:
  1. Check your Notion connection in the dashboard — reconnect your workspace if needed
  2. If using a manual notionToken:
    • Go to notion.so/my-integrations
    • Verify the integration is active (not deleted)
    • Regenerate a new secret if needed
    • Tokens start with ntn_ — check for extra spaces when copying

​
Missing API Key

For authentication issues with the Mark2Notion API key (not Notion token), see the Error Handling page.

​
Rate Limiting and Usage

​
Quota Exceeded

Error Message:
Usage quota exceeded for current billing period
What This Means: You’ve reached your monthly API request limit for your current plan.Solutions:
  1. Check your usage:
    • Monitor your usage in the dashboard
  2. Wait for reset:
    • Free tier quotas reset monthly
    • Check when your next billing period starts
  3. Upgrade your plan:
    • Visit the dashboard to upgrade to a higher tier
    • Higher tiers offer more requests per month
See Error Handling - Rate Limits for more details.

​
Usage Counter Not Found

Error Message:
No usage counter found for current period
What This Means: This is an internal error related to usage tracking initialization.Solutions:
  1. Retry the request:
    • This is usually a transient error
    • Wait a few seconds and try again
  2. If it persists:

​
Notion-Specific Errors

​
Conflict on Save

Error Message:
Conflict occurred while saving. Please try again.
What This Means: The page was modified by another user or process while your request was being processed.Solutions:
  1. Retry the request:
    • This is usually a transient error
    • Wait a few seconds and try again
    • Use exponential backoff (wait longer between each retry)
  2. Avoid concurrent edits:
    • Don’t make multiple simultaneous requests to the same page
    • Implement request queuing for frequent updates

​
Notion API Timeout

Error Message:
Request to Notion API has timed out
What This Means: The request to Notion’s API took too long and timed out.Common Causes:
  • Very large content being processed
  • Notion API experiencing slowdowns
  • Complex markdown with many blocks
Solutions:
  1. Retry the request:
    • Notion may be experiencing temporary issues
    • Wait a few seconds before retrying
  2. Break up large requests:
    • If sending very large content, split it into smaller chunks
    • Send chunks separately with small delays between requests
    • This prevents timeouts and improves reliability
  3. Monitor Notion status:

​
Still Having Issues?

If you’re experiencing an error not covered here:

Report an Issue

Report bugs or unexpected errors on GitHub

Contact Support

Get help from our support team
When reporting issues, include:
  • The full error message
  • The endpoint you’re calling
  • A minimal example that reproduces the issue
  • Relevant request data (without sensitive tokens)
Check the Error Handling page for general error formats and best practices for handling API errors in your code.