Troubleshooting Guide

Common issues and solutions when working with Devcogent APIs and SDKs.

Authentication Issues

Invalid API Key

Problem: Getting 401 Unauthorized errors

Symptoms:

• 401 Unauthorized responses
• Error message: "Invalid API key"

Solutions:

1. Verify your API key is correct
2. Check if the key has been revoked or expired
3. Ensure you're using the right environment (dev/staging/prod)

// Test your API key
async function testApiKey() {
  try {
    const response = await fetch('https://api.devcogent.com/v1/auth/test', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    if (response.ok) {
      console.log('✅ API key is valid');
    } else {
      console.log('❌ API key is invalid');
    }
  } catch (error) {
    console.error('Error testing API key:', error);
  }
}

Token Expiration

Problem: OAuth access tokens expiring

Symptoms:

• Working requests suddenly start failing
• Error message: "Token expired"

Solutions:

// Implement automatic token refresh
class TokenManager {
  async makeRequest(url, options = {}) {
    let token = this.getStoredToken();
    
    if (this.isTokenExpired(token)) {
      token = await this.refreshToken();
    }
    
    return fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        ...options.headers
      }
    });
  }
  
  isTokenExpired(token) {
    if (!token || !token.expires_at) return true;
    return Date.now() >= token.expires_at * 1000;
  }
}

Network and Connectivity Issues

Connection Timeouts

Problem: Requests timing out

Symptoms:

• ECONNRESET errors
• ETIMEDOUT errors
• Requests hanging indefinitely

Solutions:

1. Increase timeout values:

const client = new Devcogent({
  apiKey: process.env.DEVCOGENT_API_KEY,
  timeout: 60000 // 60 seconds
});

2. Implement retry logic:

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

DNS Resolution Issues

Problem: Cannot resolve api.devcogent.com

Symptoms:

• ENOTFOUND errors
• "Host not found" messages

Solutions:

1. Check DNS configuration:

# Test DNS resolution
nslookup api.devcogent.com
dig api.devcogent.com

# Try different DNS servers
nslookup api.devcogent.com 8.8.8.8

2. Use IP address temporarily:

// For testing only - not recommended for production
const client = new Devcogent({
  apiKey: process.env.DEVCOGENT_API_KEY,
  baseURL: 'https://1.2.3.4' // Replace with actual IP
});

Rate Limiting Issues

Exceeding Rate Limits

Problem: Getting 429 Too Many Requests

Symptoms:

• 429 Too Many Requests responses
• Error message: "Rate limit exceeded"

Solutions:

1. Implement rate limiting:

class RateLimiter {
  constructor(requestsPerMinute) {
    this.requests = [];
    this.limit = requestsPerMinute;
  }
  
  async waitIfNeeded() {
    const now = Date.now();
    const oneMinuteAgo = now - 60000;
    
    // Remove old requests
    this.requests = this.requests.filter(time => time > oneMinuteAgo);
    
    if (this.requests.length >= this.limit) {
      const oldestRequest = Math.min(...this.requests);
      const waitTime = 60000 - (now - oldestRequest);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
    
    this.requests.push(now);
  }
}

2. Handle 429 responses:

async function makeRequestWithRateLimit(requestFn) {
  try {
    return await requestFn();
  } catch (error) {
    if (error.status === 429) {
      const retryAfter = error.headers['retry-after'] || 60;
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return await requestFn(); // Retry once
    }
    throw error;
  }
}

Data and Response Issues

Invalid Response Format

Problem: Unexpected response format

Symptoms:

• JSON parsing errors
• Missing expected fields
• Type errors

Solutions:

1. Validate responses:

function validateResponse(response, expectedSchema) {
  if (!response.success) {
    throw new Error(`API Error: ${response.error?.message || 'Unknown error'}`);
  }
  
  if (!response.data) {
    throw new Error('Missing data in response');
  }
  
  // Add your validation logic here
  return response;
}

// Usage
try {
  const response = await client.getData();
  const validatedResponse = validateResponse(response, dataSchema);
  return validatedResponse.data;
} catch (error) {
  console.error('Response validation failed:', error);
}

2. Handle partial failures:

function processResponse(response) {
  const results = {
    successful: [],
    failed: []
  };
  
  response.data.forEach(item => {
    if (item.error) {
      results.failed.push({
        id: item.id,
        error: item.error
      });
    } else {
      results.successful.push(item);
    }
  });
  
  return results;
}

Large Response Handling

Problem: Memory issues with large datasets

Symptoms:

• Out of memory errors
• Slow response processing
• Application crashes

Solutions:

1. Use pagination:

async function processAllData(processFn) {
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await client.getData({
      page: page,
      limit: 100 // Process in smaller chunks
    });
    
    await processFn(response.data);
    
    hasMore = response.data.length === 100;
    page++;
    
    // Optional: Add delay to prevent overwhelming the API
    await new Promise(resolve => setTimeout(resolve, 100));
  }
}

2. Stream processing:

const stream = client.getDataStream();

stream.on('data', (chunk) => {
  // Process each chunk as it arrives
  processChunk(chunk);
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

stream.on('end', () => {
  console.log('Stream processing complete');
});

SDK-Specific Issues

Version Compatibility

Problem: SDK version conflicts

Symptoms:

• Method not found errors
• Unexpected behavior
• Breaking changes

Solutions:

1. Check SDK version:

const { version } = require('@devcogent/sdk/package.json');
console.log('SDK Version:', version);

// Check if method exists before calling
if (typeof client.newMethod === 'function') {
  await client.newMethod();
} else {
  console.warn('newMethod not available in this SDK version');
  // Use alternative approach
}

2. Pin SDK versions:

{
  "dependencies": {
    "@devcogent/sdk": "~1.2.3"
  }
}

Memory Leaks

Problem: Application memory usage growing over time

Symptoms:

• Increasing memory usage
• Performance degradation
• Out of memory crashes

Solutions:

1. Properly close connections:

class DevcogentManager {
  constructor() {
    this.client = new Devcogent({
      apiKey: process.env.DEVCOGENT_API_KEY
    });
  }
  
  async cleanup() {
    if (this.client) {
      await this.client.disconnect();
      this.client = null;
    }
  }
}

// Handle process termination
process.on('SIGTERM', async () => {
  await devcogentManager.cleanup();
  process.exit(0);
});

2. Monitor memory usage:

setInterval(() => {
  const memUsage = process.memoryUsage();
  console.log({
    rss: Math.round(memUsage.rss / 1024 / 1024) + ' MB',
    heapTotal: Math.round(memUsage.heapTotal / 1024 / 1024) + ' MB',
    heapUsed: Math.round(memUsage.heapUsed / 1024 / 1024) + ' MB'
  });
}, 30000);

Environment-Specific Issues

Development vs Production

Problem: Works in development but fails in production

Symptoms:

• Different behavior between environments
• Missing environment variables
• Network restrictions

Solutions:

1. Environment configuration checker:

function validateEnvironment() {
  const required = [
    'DEVCOGENT_API_KEY',
    'NODE_ENV'
  ];
  
  const missing = required.filter(key => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`Missing environment variables: ${missing.join(', ')}`);
  }
  
  console.log('✅ Environment validation passed');
}

// Call before initializing client
validateEnvironment();

2. Environment-specific debugging:

const client = new Devcogent({
  apiKey: process.env.DEVCOGENT_API_KEY,
  debug: process.env.NODE_ENV === 'development',
  logging: {
    level: process.env.NODE_ENV === 'production' ? 'error' : 'debug'
  }
});

Debugging Tools

Enable Debug Logging

// Enable detailed logging
const client = new Devcogent({
  apiKey: process.env.DEVCOGENT_API_KEY,
  debug: true,
  logging: {
    level: 'debug',
    requests: true,
    responses: true
  }
});

Request/Response Inspection

// Intercept and log all requests/responses
client.interceptors.request.use((config) => {
  console.log('Request:', {
    method: config.method,
    url: config.url,
    headers: config.headers,
    data: config.data
  });
  return config;
});

client.interceptors.response.use(
  (response) => {
    console.log('Response:', {
      status: response.status,
      headers: response.headers,
      data: response.data
    });
    return response;
  },
  (error) => {
    console.error('Response Error:', {
      status: error.status,
      message: error.message,
      response: error.response?.data
    });
    return Promise.reject(error);
  }
);

Health Check Endpoint

app.get('/debug/devcogent', async (req, res) => {
  try {
    const startTime = Date.now();
    
    // Test API connectivity
    const testResponse = await client.ping();
    const responseTime = Date.now() - startTime;
    
    res.json({
      status: 'healthy',
      responseTime: `${responseTime}ms`,
      apiVersion: testResponse.version,
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    res.status(500).json({
      status: 'unhealthy',
      error: error.message,
      timestamp: new Date().toISOString()
    });
  }
});

Getting Additional Help

If you're still experiencing issues:

1. Check our status page: status.devcogent.com
2. Review API documentation: API Integration Guide
3. Contact support: Support Center
4. Community forum: Community discussions

Support Information to Include

When contacting support, please include:

• SDK version and platform
• Complete error messages and stack traces
• Minimal code example that reproduces the issue
• Environment details (Node.js version, OS, etc.)
• Request/response logs (with sensitive data removed)
• Expected vs actual behavior

Next Steps

• Review API Integration Guide for best practices
• Check Authentication Guide for security issues
• Explore Deployment Guide for production considerations