Troubleshooting

Common issues and solutions for BoardAPI integration.

Authentication Issues

401 Unauthorized

Error

json

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Causes:

API key is incorrect or expired
API key not included in request headers
Organization is deactivated

Solution:

bash

# Check your API key format
curl -X GET https://api.boardapi.io/api/v1/organizations \
  -H "X-API-Key: org_live_xxxxxxxxxxxxxxxx"

# Verify organization status
# Visit: https://app.boardapi.io/developer

403 Forbidden

Error

json

{
  "statusCode": 403,
  "message": "Insufficient permissions"
}

Causes:

Using guest link to access admin features
Organization quota exceeded
Feature not available on current plan

Solution:

Use host link for admin actions
Check quota: GET /api/v1/quota
Upgrade plan if needed

Board Loading Issues

Blank Screen After Opening Link

Causes:

Board expired
Token is invalid
CORS blocking iframe

Debug Steps:

Check browser console:

javascript

// Open DevTools (F12) and look for errors
// Common error: "Refused to display in frame"

Verify board exists:

bash

curl -X GET https://api.boardapi.io/api/v1/boards/abc-123 \
  -H "X-API-Key: your-api-key"

Check token expiration:
- Tokens expire after board expiration time
- Create new board or extend expiration

Solution:

bash

# Extend board expiration
curl -X PATCH https://api.boardapi.io/api/v1/boards/abc-123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_hours": 48
  }'

Canvas Not Responding

Causes:

Too many elements (1000+)
Browser performance issues
WebSocket disconnected

Solution:

Enable pagination: ?pagination=true
Clear old boards
Check WebSocket connection in DevTools Network tab

WebSocket Issues

Connection Refused

Error

WebSocket connection failed: wss://api.boardapi.io/ws

Causes:

Missing or invalid token
Firewall blocking WebSocket
Server under maintenance

Debug:

javascript

const ws = new WebSocket('wss://api.boardapi.io/ws?token=...');

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = (event) => {
  console.log('Close code:', event.code);
  console.log('Close reason:', event.reason);
};

Common Close Codes:

1000 - Normal closure
1006 - Abnormal closure (check network)
1008 - Policy violation (invalid token)

Events Not Received

Causes:

Not subscribed to correct events
Event filtering too strict
WebSocket reconnection lag

Solution:

javascript

// Subscribe to all events
ws.send(JSON.stringify({
  type: 'subscribe',
  events: ['*'] // Or specific: ['element.added', 'element.updated']
}));

// Verify subscription
ws.onmessage = (event) => {
  console.log('Received:', event.data);
};

Webhook Issues

Webhooks Not Firing

Causes:

Webhook URL unreachable
SSL certificate invalid
Response timeout (>30s)

Debug:

bash

# Check webhook status
curl -X GET https://api.boardapi.io/api/v1/webhooks \
  -H "X-API-Key: your-api-key"

# Response shows delivery stats:
{
  "webhooks": [{
    "id": "wh_123",
    "url": "https://your-app.com/webhook",
    "failed_deliveries": 5,
    "last_error": "Connection timeout"
  }]
}

Solution:

Ensure webhook endpoint responds within 30s
Return 200 OK immediately, process async
Check firewall allows BoardAPI IPs

Duplicate Webhook Deliveries

Cause: Webhook retries on failure

Solution:

javascript

// Implement idempotency
const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const eventId = req.body.event_id;

  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }

  processedEvents.add(eventId);
  // Process event...
  res.status(200).send('OK');
});

Custom Component Issues

Component Not Loading

Causes:

Component not published
Invalid manifest.json
JavaScript errors in component code

Debug:

bash

# Validate manifest
boardapi component validate

# Check published components
curl -X GET https://api.boardapi.io/api/v1/components \
  -H "X-API-Key: your-api-key"

Solution:

Ensure boardapi component publish succeeded
Check browser console for errors
Verify manifest schema: manifest.json

Shared State Not Syncing

Causes:

Storage not initialized
Network lag
Conflicting updates

Debug:

typescript

// Check storage connection
board.storage.onConnect(() => {
  console.log('Storage connected');
});

board.storage.onDisconnect(() => {
  console.warn('Storage disconnected');
});

// Log all updates
board.storage.onChange('*', (key, value) => {
  console.log('Storage update:', key, value);
});

Solution:

Wait for onConnect before writing
Implement retry logic for writes
Use optimistic UI updates

Rate Limiting

429 Too Many Requests

Error

json

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "retry_after": 60
}

Limits:

100 requests/minute per API key
10 WebSocket messages/second per connection

Solution:

javascript

// Implement exponential backoff
async function apiCall(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      await sleep(retryAfter * 1000);
      return apiCall(url, options, retries - 1);
    }

    return response;
  } catch (error) {
    if (retries > 0) {
      await sleep(1000 * (4 - retries));
      return apiCall(url, options, retries - 1);
    }
    throw error;
  }
}

Performance Issues

Slow Board Loading

Causes:

Too many elements
Large file attachments
Network latency

Solution:

bash

# Enable pagination
GET /api/v1/boards/abc-123/elements?limit=50&offset=0

# Use CDN for files
# Files are automatically cached at edge locations

High Memory Usage

Causes:

Memory leak in custom components
Too many WebSocket connections
Not cleaning up event listeners

Solution:

typescript

// Proper cleanup
board.lifecycle.onUnmount(() => {
  // Remove event listeners
  board.storage.offChange('score', scoreHandler);

  // Close WebSocket
  ws.close();

  // Clear references
  board = null;
});

Common Error Codes

Code	Meaning	Solution
400	Bad Request	Check request body format
401	Unauthorized	Verify API key
403	Forbidden	Check permissions/quota
404	Not Found	Verify board_uuid exists
409	Conflict	Retry with updated data
429	Rate Limited	Implement backoff
500	Server Error	Retry after 1 minute

Still Need Help?

Support Channels

Documentation:

Community:

GitHub Issues: github.com/boardapi/issues
Email Support: support@boardapi.io
Status Page: status.boardapi.io

Priority Support:

Available on Business and Enterprise plans
Response time: <4 hours
Dedicated Slack channel

Debug Checklist

Before contacting support, please provide:

[ ] API key (first 8 characters only)
[ ] Board UUID
[ ] Exact error message
[ ] Browser console logs
[ ] Network tab screenshot (DevTools)
[ ] Steps to reproduce
[ ] Expected vs actual behavior

Troubleshooting ​

Authentication Issues ​

401 Unauthorized ​

403 Forbidden ​

Board Loading Issues ​

Blank Screen After Opening Link ​

Canvas Not Responding ​

WebSocket Issues ​

Connection Refused ​

Events Not Received ​

Webhook Issues ​

Webhooks Not Firing ​

Duplicate Webhook Deliveries ​

Custom Component Issues ​

Component Not Loading ​

Shared State Not Syncing ​

Rate Limiting ​

429 Too Many Requests ​

Performance Issues ​

Slow Board Loading ​

High Memory Usage ​

Common Error Codes ​

Still Need Help? ​

Debug Checklist ​

Troubleshooting

Authentication Issues

401 Unauthorized

403 Forbidden

Board Loading Issues

Blank Screen After Opening Link

Canvas Not Responding

WebSocket Issues

Connection Refused

Events Not Received

Webhook Issues

Webhooks Not Firing

Duplicate Webhook Deliveries

Custom Component Issues

Component Not Loading

Shared State Not Syncing

Rate Limiting

429 Too Many Requests

Performance Issues

Slow Board Loading

High Memory Usage

Common Error Codes

Still Need Help?

Debug Checklist