Troubleshooting

​

Common Issues

​

Issue: “Unauthorized” Error (401)

• Missing Authorization header
• Incorrect token format
• Token not found in system

• Verify header format: Authorization: Bearer YOUR_TOKEN
• Check token was copied correctly (no extra spaces or line breaks)
• Ensure token hasn’t been deleted from the system
• Verify token exists in API Token Management page

# Test if your token format is correct
curl -v -X POST "$CONFLUENCE_API_ENDPOINT" \
  -H "Authorization: Bearer $CONFLUENCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"TEST","parentId":"123","pageTitle":"Test","content":"# Test"}'

​

Issue: “Forbidden” Error (403)

• Token expired
• Token verification failed
• Clock synchronization issue

• Check token expiration date in token management UI
• Create new token if expired
• Verify system clock is synchronized
• Check JWT token claims using jwt.io

1. Visit https://jwt.io
2. Paste your token in the debugger
3. Check the exp (expiration) claim
4. Compare with current Unix timestamp

​

Issue: “License Expired” Error (402)

• License was inactive when token was created
• Token created during trial period that has ended
• License renewal pending

• Verify current license status in Confluence settings
• Create new token with active license
• Contact admin to renew license
• Check license expiration date

​

Issue: “Already Exists” Error (400)

• Page with same title and parent already exists
• overwrite parameter set to false

• Set overwrite: true to update existing page
• Use different page title
• Verify parentId is correct
• Check for duplicate pages in the space

{
  "spaceId": "DOCS",
  "parentId": "123456789",
  "pageTitle": "API Reference",
  "content": "# Updated Content",
  "overwrite": true  // Set to true to update
}

​

Issue: “Not Found” Error (404)

• Invalid spaceId
• Invalid parentId
• Parent page deleted
• User lacks access to space/parent

• Verify space exists and ID is correct
• Confirm parent page ID is valid
• Check user has access to space/parent
• Use Confluence API to verify IDs

# Check if space exists
curl -X GET "https://your-site.atlassian.net/wiki/api/v2/spaces?keys=DOCS" \
  -H "Authorization: Bearer YOUR_CONFLUENCE_TOKEN"

# Check if parent page exists
curl -X GET "https://your-site.atlassian.net/wiki/api/v2/pages/123456789" \
  -H "Authorization: Bearer YOUR_CONFLUENCE_TOKEN"

​

Issue: “Bad Request” Error (400)

• Missing required fields
• Invalid JSON format
• Empty content
• Invalid markdown
• Special characters not escaped

• Verify all required fields present (spaceId, parentId, pageTitle, content)
• Validate JSON structure
• Check content is non-empty string
• Test markdown syntax
• Escape special characters in JSON

function validatePayload(payload) {
  const required = ['spaceId', 'parentId', 'pageTitle', 'content'];

  for (const field of required) {
    if (!payload[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }

  if (payload.content.trim().length === 0) {
    throw new Error('Content cannot be empty');
  }

  return true;
}

​

Issue: “Internal Error” Error (500)

• Server-side issue
• Temporary service disruption
• Malformed content causing processing error

• Retry request after brief delay
• Check Atlassian Status page
• Simplify content to isolate issue
• Contact support if persists

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status !== 500 || i === maxRetries - 1) {
        throw error;
      }
      await sleep(1000 * Math.pow(2, i));
    }
  }
}

​

Debugging Tips

​

Test with curl First

curl -v -X POST "$CONFLUENCE_API_ENDPOINT" \
  -H "Authorization: Bearer $CONFLUENCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "DOCS",
    "parentId": "123456789",
    "pageTitle": "Test Page",
    "content": "# Test\n\nThis is a test.",
    "overwrite": false
  }'

​

Enable Verbose Logging

curl -v -X POST "..." # Shows headers and response

axios.interceptors.request.use(request => {
  console.log('Request:', JSON.stringify(request, null, 2));
  return request;
});

axios.interceptors.response.use(
  response => {
    console.log('Response:', JSON.stringify(response.data, null, 2));
    return response;
  },
  error => {
    console.error('Error:', JSON.stringify(error.response?.data, null, 2));
    return Promise.reject(error);
  }
);

​

Validate JSON Payload

# Linux/macOS
echo '{"spaceId":"DOCS"}' | jq .

# Or use an online JSON validator

​

Check Token in JWT Debugger

1. Visit https://jwt.io
2. Paste token to view claims
3. Verify expiration (exp claim)
4. Check issued at (iat claim)
5. Verify signature (if you have the secret)

​

Inspect HTTP Headers

console.log('Headers:', {
  'Authorization': `Bearer ${token.substring(0, 20)}...`, // Never log full token
  'Content-Type': 'application/json'
});

​

Test with Minimal Content

{
  "spaceId": "DOCS",
  "parentId": "123456789",
  "pageTitle": "Test",
  "content": "# Test",
  "overwrite": false
}

​

Network Issues

​

SSL/TLS Certificate Errors

// Development only - NEVER in production!
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

​

Timeout Errors

const axios = require('axios');

const instance = axios.create({
  timeout: 30000, // 30 seconds
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

​

Proxy Issues

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

​

Performance Issues

​

Slow Response Times

• Large content size
• Network latency
• Server load

• Reduce content size
• Split large documents
• Implement caching
• Use CDN for assets

​

Rate Limiting

const pLimit = require('p-limit');

const limit = pLimit(3); // Max 3 concurrent requests

const promises = pages.map(page =>
  limit(() => importToConfluence(page))
);

await Promise.all(promises);

​

Getting Help

1. Check Documentation:
   • API Reference
   • Examples
   • Best Practices
2. Gather Information:
   • API endpoint URL
   • Request payload (remove token!)
   • Response status code
   • Response body
   • Token expiration date
   • License status
3. Contact Support:
   • Support Portal: https://yamuno.atlassian.net/servicedesk/customer/portal/2/group/2/create/51
   • Include error messages and steps to reproduce
   • Attach logs (with tokens removed!)

​

Diagnostic Checklist

• Token is valid and not expired
• License is active
• Authorization header format is correct
• All required fields are present
• JSON payload is valid
• Content is not empty
• Space ID exists and is accessible
• Parent page ID exists and is accessible
• Network connectivity is working
• No firewall blocking requests
• SSL/TLS certificates are valid
• Using correct API endpoint URL

​

Related Documentation

• API Reference - Endpoint details
• Authentication - Token management
• FAQ - Frequently asked questions