Error Handling

Error Response Format

All Mark2Notion API errors follow a consistent format to help you handle them programmatically.

Response Types

Success Response

{
  "status": "success",
  "data": {
    // Response data
  }
}

Validation Errors (400)

Used when request parameters are invalid or missing.

{
  "status": "fail",
  "data": {
    "field_name": "Error description for this field",
    "another_field": "Another validation error"
  }
}

Authentication Errors (401, 403)

{
  "status": "error",
  "message": "Authentication error description"
}

Rate Limit Errors (429)

{
  "status": "error",
  "message": "Usage quota exceeded for current billing period",
  "data": {
    "current_usage": 1000,
    "quota": 1000,
    "plan": "free",
    "requests_remaining": 0
  }
}

Server Errors (500)

{
  "status": "error",
  "message": "Internal server error description"
}

Common Error Scenarios

Authentication Issues

401 - Missing API Key

Cause: No x-api-key header providedSolution: Include your API key in the request headers

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.mark2notion.com/api/convert"

403 - Invalid API Key

Cause: API key is invalid, expired, or deactivatedSolution:

Check your API key in the dashboard
Generate a new API key if needed
Ensure your subscription is active

403 - No Active Subscription

Cause: Your subscription is inactive or cancelledSolution: Reactivate your subscription in the dashboard

Usage Limits

429 - Quota Exceeded

Cause: You’ve exceeded your monthly request quotaSolution:

Wait for your quota to reset next month
Upgrade to a higher plan
Monitor usage with response headers

Headers to monitor:

X-Usage-Current: 950
X-Usage-Quota: 1000
X-Usage-Remaining: 50

Invalid Notion Token

Error: "Invalid Notion token or insufficient permissions"Solution:

First, check that your Notion workspace is connected in the dashboard — reconnect if needed
If using a manual notionToken, verify it’s still active at notion.so/my-integrations
Ensure the integration has access to the target workspace

Page Not Found

Error: "Page not found or access denied"Causes:

Page URL or ID is incorrect
Page has been deleted
Notion connection doesn’t have access to the page

Solution:

First, check that your Notion workspace is connected in the dashboard and that the connected account has access to this page (or its parent)
Verify the page URL or ID is correct (copy directly from Notion)
If using a manual notionToken, share the page with your integration via ··· → Connections

Content Validation

Invalid Markdown

Error: {"status": "fail", "data": {"markdown": "Missing or invalid markdown content"}}Causes:

Empty markdown string
Markdown parameter missing
Content too large

Solution: Provide valid markdown content in the request body

Error Handling Best Practices

1. Check Response Status

Always check the HTTP status code and response status field:

const response = await fetch('/api/convert', {
  // ... request options
});

if (!response.ok) {
  const error = await response.json();
  
  switch (response.status) {
    case 400:
      // Handle validation errors
      console.log('Validation errors:', error.data);
      break;
    case 401:
    case 403:
      // Handle authentication errors
      console.log('Auth error:', error.message);
      break;
    case 429:
      // Handle rate limiting
      console.log('Rate limited:', error.data);
      break;
    default:
      console.log('Unexpected error:', error.message);
  }
  return;
}

const data = await response.json();
// Handle success

import requests

try:
    response = requests.post('/api/convert', json=data)
    response.raise_for_status()  # Raises exception for 4xx/5xx
    
    result = response.json()
    # Handle success
    
except requests.HTTPError as e:
    error_data = e.response.json()
    
    if e.response.status_code == 400:
        # Handle validation errors
        print("Validation errors:", error_data['data'])
    elif e.response.status_code in [401, 403]:
        # Handle authentication
        print("Auth error:", error_data['message'])
    elif e.response.status_code == 429:
        # Handle rate limiting
        print("Rate limited:", error_data['data'])
    else:
        print("Unexpected error:", error_data['message'])

2. Implement Retry Logic

For rate limiting and transient errors:

async function callAPIWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await apiCall();
      
      if (response.status === 429) {
        // Rate limited - wait and retry
        const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Wait before retrying
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

3. Monitor Usage

Track your API usage to avoid hitting limits:

function logUsageInfo(response) {
  const usage = {
    current: response.headers.get('X-Usage-Current'),
    quota: response.headers.get('X-Usage-Quota'),
    remaining: response.headers.get('X-Usage-Remaining'),
    plan: response.headers.get('X-Usage-Plan')
  };
  
  console.log('API Usage:', usage);
  
  // Warn when approaching limit
  if (usage.remaining < usage.quota * 0.1) {
    console.warn('Approaching usage limit!');
  }
}

4. Graceful Degradation

Handle errors gracefully in your application:

async function convertMarkdown(markdown) {
  try {
    const response = await callAPI('/api/convert', { markdown });
    return response.data.blocks;
  } catch (error) {
    // Log error for debugging
    console.error('Markdown conversion failed:', error);
    
    // Return fallback or throw user-friendly error
    throw new Error('Unable to convert markdown at this time. Please try again later.');
  }
}

Getting Help

If you encounter errors not covered here:

Report Issues

Report bugs or unexpected behavior

Give Feedback

Share your experience and suggestions

When reporting issues, include the full error response and the request that caused it (without sensitive data like API keys).

Getting Started

API Reference

Support

Legal

Error Response Format

Response Types

Success Response

Validation Errors (400)

Authentication Errors (401, 403)

Rate Limit Errors (429)

Server Errors (500)

Common Error Scenarios

Authentication Issues

Usage Limits

Content Validation

Error Handling Best Practices

1. Check Response Status

2. Implement Retry Logic

3. Monitor Usage

4. Graceful Degradation

Getting Help

Report Issues

Give Feedback

​Error Response Format

​Response Types

​Success Response

​Validation Errors (400)

​Authentication Errors (401, 403)

​Rate Limit Errors (429)

​Server Errors (500)

​Common Error Scenarios

​Authentication Issues

​Usage Limits

​Notion-Related Errors

​Content Validation

​Error Handling Best Practices

​1. Check Response Status

​2. Implement Retry Logic

​3. Monitor Usage

​4. Graceful Degradation

​Getting Help

Report Issues

Give Feedback

Error Response Format

Response Types

Success Response

Validation Errors (400)

Authentication Errors (401, 403)

Rate Limit Errors (429)

Server Errors (500)

Common Error Scenarios

Authentication Issues

Usage Limits

Notion-Related Errors

Content Validation

Error Handling Best Practices

1. Check Response Status

2. Implement Retry Logic

3. Monitor Usage

4. Graceful Degradation

Getting Help