Troubleshooting

Common issues, solutions, and debugging tips for Chartly integration. If you can't find your answer here, contact support.

Quick Debug Checklist

Before diving into specific issues, run through this checklist:

✅ API Key: Valid and not expired?
✅ Request Format: Correct headers and JSON structure?
✅ Chart Config: Valid Chart.js configuration?
✅ Rate Limits: Within your plan's limits?
✅ Network: Can you reach api.chartly.dev?

Authentication Issues

401 Unauthorized - Invalid API Key

Symptoms:

{
  "error": "unauthorized",
  "detail": "Invalid or missing API key"
}

Common Causes & Solutions:

Missing API Key Header

# ❌ Wrong
curl "https://api.chartly.dev/v1/chart" -d '{...}'

# ✅ Correct
curl "https://api.chartly.dev/v1/chart" \
  -H "X-Api-Key: live_abc123..." \
  -d '{...}'

Wrong Header Name

// ❌ Wrong
headers: { 'API-Key': apiKey }
headers: { 'Authorization': apiKey }

// ✅ Correct
headers: { 'X-Api-Key': apiKey }

Expired Trial Key

# Check if your trial key is expired (30 days)
# Generate a new trial key or upgrade to paid plan
curl -X POST "https://api.chartly.dev/signup/anon"

Key Type Mismatch
```
# Trial keys start with trial_
```

Live keys start with live_

Test keys start with pk_test_

### 429 Trial Limit Reached

**Symptoms:**
```json
{
"error": "trial_limit_reached",
"detail": "Trial API key has reached its usage limit"
}

Solutions:

Upgrade to a paid plan
Use signed URLs for public sharing instead of regenerating charts
Optimize your chart usage patterns

401 Invalid Session Token

Symptoms:

{
  "error": "invalid_session",
  "detail": "Invalid or expired session token"
}

Solutions:

# Log in again to get a fresh session token
curl -X POST "https://api.chartly.dev/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "contact@chartly.dev", "password": "password"}'

Chart Generation Issues

400 Bad Request - Invalid Chart Configuration

Symptoms:

{
  "error": "invalid_input",
  "detail": "Invalid chart configuration"
}

Common Issues:

Missing Required Fields

// ❌ Missing data
{
  "type": "bar",
  "options": { "responsive": false }
}

// ✅ Complete config
{
  "type": "bar",
  "data": {
    "labels": ["A", "B", "C"],
    "datasets": [{"data": [1, 2, 3]}]
  },
  "options": { "responsive": false }
}

Invalid Chart Type

// ❌ Wrong
{ "type": "bars" }  // Should be "bar"
{ "type": "piechart" }  // Should be "pie"

// ✅ Correct
{ "type": "bar" }
{ "type": "pie" }

Responsive Must Be False

// ❌ Wrong for image generation
{ "options": { "responsive": true } }

// ✅ Correct
{ "options": { "responsive": false } }

Invalid Data Structure

// ❌ Wrong - missing datasets array
{
  "data": {
    "labels": ["A", "B"],
    "data": [1, 2]
  }
}

// ✅ Correct
{
  "data": {
    "labels": ["A", "B"], 
    "datasets": [{"data": [1, 2]}]
  }
}

400 Invalid Dimensions

Symptoms:

{
  "error": "invalid_dimensions",
  "detail": "Width must be between 1 and 2000 pixels"
}

Solutions:

// ❌ Wrong
{ "width": 0, "height": 400 }      // Too small
{ "width": 3000, "height": 400 }   // Too large for trial/starter

// ✅ Correct
{ "width": 600, "height": 400 }    // Within limits

500 Render Failed

Symptoms:

{
  "error": "render_failed", 
  "detail": "Chart rendering failed"
}

Common Causes:

Complex Chart Configuration
- Simplify your chart options
- Remove unnecessary plugins or animations
- Try a smaller dataset first

Invalid Color Values

// ❌ Wrong
"backgroundColor": "invalid-color"

// ✅ Correct
"backgroundColor": "rgba(255, 99, 132, 0.8)"
"backgroundColor": "#FF6384"
"backgroundColor": "red"

Function Strings in JSON

// ❌ Won't work - functions can't be serialized
{
  "options": {
    "plugins": {
      "tooltip": {
        "callbacks": {
          "label": function(context) { return context.label; }
        }
      }
    }
  }
}

// ✅ Use string representation (limited support)
{
  "options": {
    "plugins": {
      "tooltip": {
        "callbacks": {
          "label": "function(context) { return context.label; }"
        }
      }
    }
  }
}

Rate Limiting Issues

429 Rate Limit Exceeded

Symptoms:

{
  "error": "rate_limit_exceeded",
  "detail": "Rate limit exceeded. Try again in 60 seconds"
}

Solutions:

Implement Exponential Backoff

async function makeRequestWithBackoff(requestFn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Batch Requests

// ❌ Sequential requests
for (const config of chartConfigs) {
  await generateChart(config);
}

// ✅ Parallel batch (respecting rate limits)
const batchSize = 10;
for (let i = 0; i < chartConfigs.length; i += batchSize) {
  const batch = chartConfigs.slice(i, i + batchSize);
  await Promise.all(batch.map(config => generateChart(config)));
  
  // Small delay between batches
  if (i + batchSize < chartConfigs.length) {
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

Use Caching

const chartCache = new Map();

async function getCachedChart(config) {
  const key = JSON.stringify(config);
  
  if (chartCache.has(key)) {
    return chartCache.get(key);
  }
  
  const chartUrl = await chartly.createChart(config);
  chartCache.set(key, chartUrl);
  return chartUrl;
}

Network & Connectivity Issues

Connection Timeouts

Symptoms:

Requests hanging or timing out
Intermittent connection failures

Solutions:

Increase Timeout

// Node.js with fetch
const response = await fetch('https://api.chartly.dev/v1/chart', {
  method: 'POST',
  headers: { 'X-Api-Key': apiKey },
  body: JSON.stringify(chartData),
  signal: AbortSignal.timeout(30000) // 30 second timeout
});

Check Network Connectivity

# Test basic connectivity
ping api.chartly.dev

# Test HTTPS connectivity
curl -I "https://api.chartly.dev/v1/status"

Corporate Firewall/Proxy

# Check if your firewall blocks api.chartly.dev
# Whitelist: api.chartly.dev (port 443)
# Contact your IT team if needed

DNS Resolution Issues

Symptoms:

DNS_PROBE_FINISHED_NXDOMAIN
getaddrinfo ENOTFOUND api.chartly.dev

Solutions:

# Check DNS resolution
nslookup api.chartly.dev

# Try alternative DNS servers
# 8.8.8.8 (Google)
# 1.1.1.1 (Cloudflare)

Integration-Specific Issues

React Integration

Common Issue: API Key in Client-Side Code

// ❌ Wrong - exposes API key to browser
function ChartComponent() {
  const apiKey = "live_secret_key"; // Don't do this!
  
  useEffect(() => {
    fetch('https://api.chartly.dev/v1/chart', {
      headers: { 'X-Api-Key': apiKey }
    });
  }, []);
}

// ✅ Correct - proxy through your backend
function ChartComponent() {
  useEffect(() => {
    fetch('/api/generate-chart', {
      method: 'POST',
      body: JSON.stringify(chartConfig)
    });
  }, []);
}

Node.js Integration

Common Issue: Buffer Handling

// ❌ Wrong - treating binary data as text
const response = await fetch('https://api.chartly.dev/v1/chart', options);
const chartText = await response.text(); // Don't do this!

// ✅ Correct - handle as binary data
const response = await fetch('https://api.chartly.dev/v1/chart', options);
const chartBuffer = await response.arrayBuffer();

Express.js CORS Issues

// Enable CORS for chart endpoints
app.use('/api/chart', cors({
  origin: ['http://localhost:3000', 'https://yourdomain.com'],
  credentials: true
}));

Next.js API Routes

Common Issue: Missing Content-Type

// ❌ Wrong
export default async function handler(req, res) {
  const chartBuffer = await generateChart(req.body);
  res.send(chartBuffer); // Missing content-type
}

// ✅ Correct
export default async function handler(req, res) {
  const chartBuffer = await generateChart(req.body);
  res.setHeader('Content-Type', 'image/png');
  res.send(chartBuffer);
}

Performance Issues

Slow Chart Generation

Symptoms:

Long response times (>10 seconds)
Timeouts on large charts

Optimization Strategies:

Reduce Chart Complexity

// ❌ Too complex
{
  "data": {
    "labels": Array(10000).fill(0).map((_, i) => `Point ${i}`),
    "datasets": [{ "data": Array(10000).fill(0).map(() => Math.random()) }]
  }
}

// ✅ Optimized
{
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [{ "data": [100, 120, 115, 134] }]
  }
}

Disable Animations

{
  "options": {
    "responsive": false,
    "animation": false, // Faster rendering
    "elements": {
      "point": { "radius": 0 } // Remove points for line charts
    }
  }
}

Optimize Dimensions

// ❌ Unnecessarily large
{ "width": 2000, "height": 2000 }

// ✅ Appropriate size
{ "width": 600, "height": 400 }

Memory Issues

Symptoms:

Out of memory errors
Process crashes with large datasets

Solutions:

Stream Large Responses

const response = await fetch('https://api.chartly.dev/v1/chart', options);

// Stream to file instead of loading into memory
const fileStream = fs.createWriteStream('chart.png');
response.body.pipe(fileStream);

Process Data in Chunks

// Split large datasets into multiple smaller charts
const chunkSize = 100;
const chunks = [];

for (let i = 0; i < data.length; i += chunkSize) {
  chunks.push(data.slice(i, i + chunkSize));
}

Debugging Tools

Enable Debug Mode

const chartly = new ChartlyClient({
  apiKey: process.env.CHARTLY_API_KEY,
  debug: true // Enables request/response logging
});

Test Your Chart Configuration

# Test your config with curl first
curl -X POST "https://api.chartly.dev/v1/chart" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d @chart-config.json \
  --output test-chart.png \
  -v  # Verbose output for debugging

Validate Chart.js Config

Use the Chart.js documentation and online validators:

Chart.js Documentation: chartjs.org/docs
Online Chart Builder: chartjs.org/docs/latest/samples/
Config Validator: Test your config in a browser first

Check Service Status

# Check if Chartly is operational
curl "https://api.chartly.dev/v1/status"

# Expected response:
# {
#   "status": "healthy",
#   "buildHash": "abc123",
#   "kvLatency": 12
# }

Error Reference

Complete Error Code List

Code	Status	Description	Solution
`invalid_input`	400	Request validation failed	Check request format
`chart_required`	400	Missing chart config	Include chart parameter
`invalid_dimensions`	400	Width/height out of range	Use valid dimensions
`invalid_format`	400	Unsupported format	Use 'png' or 'svg'
`unauthorized`	401	Invalid/missing API key	Check API key
`invalid_session`	401	Expired session token	Login again
`forbidden`	403	Access denied	Check account status
`not_found`	404	Resource not found	Check URL/ID
`email_exists`	409	Email already registered	Use different email
`rate_limit_exceeded`	429	Too many requests	Implement rate limiting
`trial_limit_reached`	429	Trial usage exhausted	Upgrade account
`payload_too_large`	413	Request body too large	Reduce chart complexity
`internal_error`	500	Server error	Try again or contact support
`render_failed`	500	Chart rendering failed	Simplify chart config
`service_unavailable`	503	Temporary downtime	Try again later

Getting Help

Try Again Later: If the service is temporarily unavailable
Contact Support: Include error details and request ID
Community Forum: Ask questions and help others

Support Information to Include

When contacting support, please include:

Error message: Complete error response
Request details: Headers, body, API endpoint
API key prefix: First 8 characters (live_abc12...)
Timestamp: When the error occurred
Request ID: If available in response headers

Still need help? Contact us:

📧 Support: contact@chartly.dev

Quick Debug Checklist​

Authentication Issues​

401 Unauthorized - Invalid API Key​

Live keys start with live_

Test keys start with pk_test_

401 Invalid Session Token​

Chart Generation Issues​

400 Bad Request - Invalid Chart Configuration​

400 Invalid Dimensions​

500 Render Failed​

Rate Limiting Issues​

429 Rate Limit Exceeded​

Network & Connectivity Issues​

Connection Timeouts​

DNS Resolution Issues​

Integration-Specific Issues​

React Integration​

Node.js Integration​

Express.js CORS Issues​

Next.js API Routes​

Performance Issues​

Slow Chart Generation​

Memory Issues​

Debugging Tools​

Enable Debug Mode​

Test Your Chart Configuration​

Validate Chart.js Config​

Check Service Status​

Error Reference​

Complete Error Code List​

Getting Help​

Support Information to Include​

Quick Debug Checklist

Authentication Issues

401 Unauthorized - Invalid API Key

401 Invalid Session Token

Chart Generation Issues

400 Bad Request - Invalid Chart Configuration

400 Invalid Dimensions

500 Render Failed

Rate Limiting Issues

429 Rate Limit Exceeded

Network & Connectivity Issues

Connection Timeouts

DNS Resolution Issues

Integration-Specific Issues

React Integration

Node.js Integration

Express.js CORS Issues

Next.js API Routes

Performance Issues

Slow Chart Generation

Memory Issues

Debugging Tools

Enable Debug Mode

Test Your Chart Configuration

Validate Chart.js Config

Check Service Status

Error Reference

Complete Error Code List

Getting Help

Support Information to Include