Skip to main content

Troubleshooting

This guide helps you diagnose and resolve common issues when working with the NUVA Labs APIs.

Common Issues​

Authentication Errors​

401 Unauthorized​

Symptoms:

  • API calls return 401 status code
  • "Invalid API key" error messages

Solutions:

  1. Verify API Key:

    curl -H "Authorization: Bearer YOUR_API_KEY" \
         https://api.provlabs.com/accounts/test

  2. Check Key Format:

    • Ensure key starts with pk_ or sk_
    • No extra spaces or characters
    • Key is properly URL-encoded

  3. Regenerate Key:

    • Log into your account
    • Generate a new API key
    • Update your application configuration

403 Forbidden​

Symptoms:

  • API calls return 403 status code
  • "Insufficient permissions" error messages

Solutions:

  1. Check API Key Permissions:

    • Verify key has required scopes
    • Check if key is restricted to specific endpoints

  2. Review Account Status:

    • Ensure account is active
    • Check for any restrictions or suspensions

Rate Limiting​

429 Too Many Requests​

Symptoms:

  • API calls return 429 status code
  • "Rate limit exceeded" error messages

Solutions:

  1. Implement Exponential Backoff:

    async function withRetry(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (error.status === 429) {
            const delay = Math.pow(2, i) * 1000;
            await new Promise((resolve) => setTimeout(resolve, delay));
          } else {
            throw error;
          }
        }
      }
    }

  2. Optimize API Usage:

    • Use batch endpoints when available
    • Implement caching for frequently accessed data
    • Reduce unnecessary API calls

  3. Monitor Rate Limits:

    // Check rate limit headers
    const response = await fetch('/api/endpoint');
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const resetTime = response.headers.get('X-RateLimit-Reset');

Network Issues​

Connection Timeouts​

Symptoms:

  • Requests timeout after 30+ seconds
  • "Connection timeout" error messages

Solutions:

  1. Increase Timeout:

    const apiClient = axios.create({
      timeout: 60000, // 60 seconds
      baseURL: 'https://api.provlabs.com',
    });

  2. Implement Retry Logic:

    async function retryRequest(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (i === maxRetries - 1) throw error;
          await delay(1000 * (i + 1));
        }
      }
    }

  3. Check Network Connectivity:

    ping api.provlabs.com
    curl -I https://api.provlabs.com/health

DNS Resolution Issues​

Symptoms:

  • "Could not resolve host" errors
  • Intermittent connection failures

Solutions:

  1. Use Alternative DNS:

    • Try Google DNS (8.8.8.8)
    • Try Cloudflare DNS (1.1.1.1)

  2. Check DNS Cache:

    # macOS/Linux
    sudo dscacheutil -flushcache

    # Windows
    ipconfig /flushdns

Data Issues​

Invalid Request Format​

Symptoms:

  • 400 Bad Request errors
  • "Invalid JSON" or "Missing required field" messages

Solutions:

  1. Validate Request Data:

    function validateTransferData(data) {
      const required = ['fromAddress', 'toAddress', 'amount', 'assetId'];
      const missing = required.filter((field) => !data[field]);

      if (missing.length > 0) {
        throw new Error(`Missing required fields: ${missing.join(', ')}`);
      }

      return true;
    }

  2. Check Data Types:

    • Ensure amounts are strings, not numbers
    • Verify addresses are valid format
    • Check date formats (ISO 8601)

  3. Use API Documentation:

    • Reference the API docs for exact field requirements
    • Use provided examples as templates

Missing Data​

Symptoms:

  • Empty responses
  • "Not found" errors for valid requests

Solutions:

  1. Check Request Parameters:

    • Verify all required parameters are included
    • Check parameter values are correct

  2. Handle Pagination:

    async function getAllData(endpoint) {
      let allData = [];
      let offset = 0;
      const limit = 100;

      while (true) {
        const response = await apiClient.get(endpoint, {
          params: { limit, offset },
        });

        allData.push(...response.data.items);

        if (response.data.items.length < limit) break;
        offset += limit;
      }

      return allData;
    }

WebSocket Issues​

Connection Drops​

Symptoms:

  • WebSocket disconnects unexpectedly
  • "Connection lost" error messages

Solutions:

  1. Implement Reconnection:

    class WebSocketManager {
      constructor(url, apiKey) {
        this.url = url;
        this.apiKey = apiKey;
        this.ws = null;
        this.reconnectAttempts = 0;
        this.maxReconnectAttempts = 5;
      }

      connect() {
        this.ws = new WebSocket(this.url, {
          headers: { Authorization: `Bearer ${this.apiKey}` },
        });

        this.ws.onclose = () => {
          if (this.reconnectAttempts < this.maxReconnectAttempts) {
            setTimeout(() => {
              this.reconnectAttempts++;
              this.connect();
            }, Math.pow(2, this.reconnectAttempts) * 1000);
          }
        };
      }
    }

  2. Handle Heartbeat:

    // Send ping every 30 seconds
    setInterval(() => {
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: 'ping' }));
      }
    }, 30000);

Subscription Issues​

Symptoms:

  • Subscriptions not working
  • No data received after subscribing

Solutions:

  1. Verify Subscription Format:

    const subscription = {
      action: 'subscribe',
      channel: 'transactions',
      params: { address: 'valid_address' },
    };

    ws.send(JSON.stringify(subscription));

  2. Check Authentication:

    • Ensure WebSocket connection is authenticated
    • Verify API key has required permissions

Debugging Tools​

API Testing​

Use tools like Postman or curl to test API endpoints:

# Test authentication
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.provlabs.com/accounts/test

# Test specific endpoint
curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"fromAddress":"addr1","toAddress":"addr2","amount":"100"}' \
     https://api.provlabs.com/transfers

Logging​

Implement comprehensive logging:

const winston = require('winston');

const logger = winston.createLogger({
  level: 'debug',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'api.log' }),
  ],
});

// Log API requests
logger.debug('API Request', {
  method: 'POST',
  url: '/transfers',
  data: requestData,
});

// Log API responses
logger.debug('API Response', {
  status: response.status,
  data: response.data,
});

Monitoring​

Set up monitoring and alerting:

// Monitor API health
setInterval(async () => {
  try {
    const response = await fetch('https://api.provlabs.com/health');
    if (!response.ok) {
      console.error('API health check failed');
      // Send alert
    }
  } catch (error) {
    console.error('API health check error:', error);
    // Send alert
  }
}, 60000); // Check every minute

Performance Issues​

Slow Response Times​

Symptoms:

  • API calls take longer than expected
  • Timeout errors

Solutions:

  1. Optimize Requests:

    • Use specific endpoints instead of generic ones
    • Implement proper caching
    • Reduce payload size

  2. Use CDN:

    • Cache static data
    • Use regional endpoints when available

  3. Monitor Performance:

    const startTime = Date.now();
    const response = await apiCall();
    const duration = Date.now() - startTime;

    if (duration > 5000) {
      console.warn(`Slow API call: ${duration}ms`);
    }

Memory Issues​

Symptoms:

  • High memory usage
  • Application crashes

Solutions:

  1. Implement Pagination:

    • Don't load all data at once
    • Use streaming for large datasets

  2. Clean Up Resources:

    // Close WebSocket connections
    ws.close();

    // Clear intervals
    clearInterval(heartbeatInterval);

    // Remove event listeners
    ws.removeAllListeners();

Getting Help​

Documentation​

  1. API Reference: Check the API documentation
  2. Code Examples: Review provided examples
  3. Changelog: Check for recent changes

Support Channels​

  1. GitHub Issues: Report bugs and request features
  2. Discord Community: Get help from other developers
  3. Email Support: Contact support for urgent issues

Reporting Issues​

When reporting issues, include:

  1. Error Details:

    • Full error message
    • HTTP status code
    • Request/response data

  2. Environment:

    • Programming language and version
    • Operating system
    • API key type (test/production)

  3. Steps to Reproduce:

    • Exact API calls made
    • Request data
    • Expected vs actual behavior

Next Steps​

Ready to start building? Let's explore Integration Patterns for advanced integration techniques!