​

Troubleshooting Guide

This guide covers common issues developers encounter when integrating with the CHRT API and provides step-by-step solutions.

​

Authentication Issues

​

Invalid API Key Error (401)

Error Message: {"error": "Invalid API key", "code": 401} Common Causes:

• Incorrect API key format or typo
• Using test key in live environment (or vice versa)
• Key has been revoked or expired
• Wrong authentication header format

Solutions:

1. Verify Key Format:
   Copy

   # Public keys start with pk_
   pk_test_1234567890abcdef
   pk_live_1234567890abcdef
   
   # Secret keys start with sk_
   sk_test_1234567890abcdef.randomstring  
   sk_live_1234567890abcdef.randomstring
   

2. Check Environment Match:
   • Use pk_test_ or sk_test_ keys for development
   • Use pk_live_ or sk_live_ keys for production
3. Verify Header Format:
   Copy

   # Correct - Bearer token (recommended)
   Authorization: Bearer sk_test_1234567890abcdef.randomstring
   
   # Alternative - Custom header
   X-CHRT-API-Key: pk_test_1234567890abcdef
   

4. Check Key Status: Go to Dashboard → API Keys and verify the key is active

​

Forbidden Error (403)

Error Message: {"error": "Insufficient permissions", "code": 403} Common Causes:

• API key lacks required scopes for the endpoint
• Domain/IP restrictions blocking the request
• Using public key for server-side operations

Solutions:

1. Check Key Scopes: Verify your key has the required permissions:
   • enc.tiles:read - For map tile requests
   • features.search:read - For chart feature queries
   • query.spatial:read - For spatial queries
2. Review Domain Restrictions (Public Keys):
   • Ensure your domain is listed in allowed origins
   • Check for typos in domain configuration
   • Verify protocol (http vs https) matches
3. Check IP Restrictions (Secret Keys):
   • Verify your server IP is in the allowlist
   • Use CIDR notation for IP ranges: 192.168.1.0/24
4. Use Correct Key Type:
   • Use secret keys for server-side API calls
   • Use public keys only for client-side/browser requests

​

Rate Limiting Issues

​

Rate Limit Exceeded (429)

Error Message: {"error": "Rate limit exceeded", "code": 429, "retry_after": 60} Understanding Rate Limits:

• Per-key limits: Based on your subscription plan
• Global limits: Protect overall system stability
• Sliding window: Resets continuously, not at fixed intervals

Solutions:

1. Implement Exponential Backoff:
   Copy

   async function apiCallWithRetry(url, options, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         const response = await fetch(url, options);
         
         if (response.status === 429) {
           const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
           await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
           continue;
         }
         
         return response;
       } catch (error) {
         if (i === maxRetries - 1) throw error;
       }
     }
   }
   

2. Optimize Request Patterns:
   • Batch multiple operations into single requests
   • Cache responses to avoid repeated calls
   • Use appropriate polling intervals
3. Upgrade Your Plan: Higher tiers have increased rate limits
4. Request Rate Limit Increase: Contact support for custom limits

​

Chart Data Issues

​

No Chart Data Available

Error Message: {"error": "No chart data available for this area", "code": 404} Common Causes:

• Requesting data outside covered geographic areas
• Coordinates in wrong format (lat/lon swapped)
• Zoom level too high for available chart detail

Solutions:

1. Verify Geographic Coverage:
   Copy

   # Check coverage for your area
   curl "https://api.chrt.co/v1/coverage?bbox=-71.5,42.0,-70.5,43.0" \
     -H "Authorization: Bearer YOUR_API_KEY"
   

2. Check Coordinate Format:
   Copy

   // Correct: [longitude, latitude]
   const bbox = [-71.0557, 42.3601, -71.0402, 42.3735]; // Boston Harbor
   
   // Incorrect: [latitude, longitude] - will return no data
   const wrongBbox = [42.3601, -71.0557, 42.3735, -71.0402];
   

3. Adjust Zoom Levels:
   • Start with lower zoom levels (1-10) for broad areas
   • Use higher zoom levels (11-18) only for detailed coastal areas
4. Check ENC Status: Visit the ENC Status page for data availability

​

Outdated Chart Information

Symptoms: Chart data appears old or doesn’t match recent changes Solutions:

1. Check Data Freshness:
   Copy

   curl "https://api.chrt.co/v1/status/freshness?bbox=YOUR_BOUNDS" \
     -H "Authorization: Bearer YOUR_API_KEY"
   

2. Clear Application Cache: Remove cached chart data from your application
3. Report Data Issues: Contact support with specific coordinates and expected information

​

Network and Connectivity Issues

​

Request Timeouts

Common Causes:

• Large geographic areas requiring significant processing
• Network connectivity issues
• Server maintenance or high load

Solutions:

1. Increase Timeout Settings:
   Copy

   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 second timeout
   
   try {
     const response = await fetch(url, {
       signal: controller.signal,
       headers: { 'Authorization': `Bearer ${apiKey}` }
     });
     clearTimeout(timeoutId);
   } catch (error) {
     if (error.name === 'AbortError') {
       console.log('Request timed out');
     }
   }
   

2. Reduce Request Size: Break large areas into smaller bounding boxes
3. Implement Retry Logic: Retry failed requests with exponential backoff

​

CORS Errors (Browser Only)

Error Message: Access to fetch at 'https://api.chrt.co' from origin 'https://yourdomain.com' has been blocked by CORS policy Solutions:

1. Add Domain to API Key: Go to Dashboard → API Keys → Edit → Add your domain to allowed origins
2. Check Domain Format:
   Copy

   # Correct formats
   https://yourdomain.com
   https://*.yourdomain.com  (for subdomains)
   http://localhost:3000     (for development)
   
   # Incorrect formats  
   yourdomain.com           (missing protocol)
   https://yourdomain.com/  (trailing slash)
   

3. Use Public Keys: Only public keys work with CORS/browser requests
4. Development Setup: Add localhost domains for local testing

​

Integration Issues

​

Chart Tiles Not Loading

Symptoms: Map displays but chart overlays don’t appear Debugging Steps:

1. Check Network Tab: Look for 404 or authentication errors
2. Verify Tile URL Format:
   Copy

   // Correct tile URL pattern
   const tileUrl = `https://api.chrt.co/v1/tiles/{z}/{x}/{y}.png?api_key=${publicKey}`;
   

3. Test Direct Tile Access: Try accessing a tile URL directly in browser

​

Feature Queries Returning Empty Results

Common Issues:

• Bounding box too small or in areas without chart features
• Incorrect query parameters
• Missing required scopes on API key

Solutions:

1. Expand Search Area: Try larger bounding boxes
2. Check Query Syntax:
   Copy

   curl "https://api.chrt.co/v1/features?bbox=-71.1,42.3,-71.0,42.4&types=buoy,lighthouse" \
     -H "Authorization: Bearer YOUR_API_KEY"
   

3. Verify Feature Types: Check available feature types in documentation

​

Performance Optimization

​

Slow API Responses

Optimization Strategies:

1. Implement Caching:
   Copy

   // Simple in-memory cache
   const cache = new Map();
   
   async function cachedApiCall(url, options) {
     if (cache.has(url)) {
       return cache.get(url);
     }
     
     const response = await fetch(url, options);
     const data = await response.json();
     cache.set(url, data);
     return data;
   }
   

2. Use Appropriate Precision: Don’t request more precision than needed
3. Batch Requests: Combine multiple operations when possible
4. CDN Integration: Use a CDN for tile caching

​

High Bandwidth Usage

Reduction Strategies:

1. Optimize Tile Requests: Only request visible tiles
2. Implement Smart Caching: Cache frequently accessed data
3. Use Compression: Enable gzip compression in your client
4. Monitor Usage: Track bandwidth consumption in dashboard

​

Getting Help

​

Before Contacting Support

1. Check Status Page: Visit https://status.chrt.co for known issues
2. Review This Guide: Ensure you’ve tried relevant solutions
3. Test with Different Keys: Try both test and live environments
4. Check Recent Changes: Consider recent code or configuration changes

​

When Contacting Support

Include the following information:

• API Key ID (not the full key): First and last 4 characters
• Request Details: Full API request including headers
• Error Response: Complete error message and HTTP status code
• Geographic Area: Coordinates or region affected
• Timestamp: When the issue occurred
• Browser/Environment: If relevant to the issue

​

Support Channels

• Documentation: https://docs.chrt.co
• Community: https://community.chrt.co
• Email: [email protected]
• Status Updates: https://status.chrt.co

​

Emergency Support

For production-critical issues:

• Enterprise Customers: Use priority support channel
• All Users: Clearly mark emails as “URGENT” with impact description
• Status Page: Check for ongoing incidents before reporting