Theme

Troubleshooting ​

This guide helps you resolve common issues when working with the De. platform.

Authentication Issues ​

API Key Not Working ​

Symptoms:

  • 401 Unauthorized errors
  • "Invalid API key" messages
  • Authentication failures

Solutions:

  1. Verify API key format - Check for copy/paste errors or extra whitespace
  2. Check environment - Ensure you're using the correct key for your environment (development vs. production)
  3. Key permissions - Verify the API key has the required permissions for the requested operation
  4. Key rotation - Check if the key has been recently rotated or expired
  5. API version - Confirm you're using the correct API version header with your request

JWT Token Issues ​

Symptoms:

  • Session timeouts
  • "Invalid token" errors
  • Unexpected logouts

Solutions:

  1. Check token expiration - Tokens typically expire after 24 hours
  2. Refresh flow - Implement proper token refresh using refresh tokens
  3. Token storage - Store tokens securely and avoid local storage for sensitive applications
  4. Token signing - Verify the correct JWT signing method is being used (RS256)

API Request Problems ​

Rate Limiting ​

Symptoms:

  • 429 Too Many Requests errors
  • Throttled responses
  • Service degradation

Solutions:

  1. Implement backoff - Use exponential backoff for retries
  2. Request batching - Batch multiple operations into single requests where possible
  3. Caching - Implement client-side caching for frequently accessed data
  4. Quota increase - Contact support for rate limit increases if needed

Request Validation Errors ​

Symptoms:

  • 400 Bad Request errors
  • Validation error messages
  • Missing required fields

Solutions:

  1. Check documentation - Review the API reference for required fields
  2. Request formatting - Ensure proper JSON structure and content types
  3. Data types - Verify correct data types for all fields (string vs. number vs. boolean)
  4. Schema validation - Implement client-side schema validation before sending requests

SDK Integration Issues ​

SDK Initialization Failures ​

Symptoms:

  • Console errors during initialization
  • SDK methods not available
  • Configuration rejected

Solutions:

  1. Check dependencies - Ensure all peer dependencies are installed
  2. Configuration - Verify all required config parameters are provided
  3. Version compatibility - Check compatibility between SDK version and backend services
  4. Browser support - Verify browser compatibility (especially for older browsers)

Map Rendering Issues ​

Symptoms:

  • Blank or partially loaded maps
  • JavaScript errors in console
  • Performance issues

Solutions:

  1. API keys - Ensure map provider API keys are valid and have correct permissions
  2. DOM container - Verify map container element exists and has proper dimensions
  3. Asset loading - Check network tab for 404 errors on map assets
  4. Console errors - Look for specific error messages in the browser console
  5. Memory leaks - Ensure maps are properly destroyed when components unmount

Webhooks and Events ​

Missing Webhook Events ​

Symptoms:

  • Expected webhooks not received
  • Inconsistent event delivery
  • Events missing specific data

Solutions:

  1. Webhook registration - Verify webhooks are properly registered in dashboard
  2. Endpoint availability - Ensure your endpoint is publicly accessible
  3. Response codes - Your webhook endpoint must return a 2xx status code quickly
  4. Event types - Check that you're subscribed to the correct event types
  5. Retry settings - Configure webhook retry settings for failed deliveries

Event Processing Failures ​

Symptoms:

  • Events received but not processed
  • Duplicate event handling
  • Event ordering issues

Solutions:

  1. Idempotency - Implement idempotent event handlers
  2. Event validation - Validate webhook signatures
  3. Async processing - Process events asynchronously to prevent timeouts
  4. Logging - Implement detailed logging for webhook processing

Network and Connectivity ​

Connection Timeouts ​

Symptoms:

  • Requests timing out
  • Slow responses
  • Intermittent connectivity

Solutions:

  1. Network stability - Check your network connection
  2. Firewall settings - Verify firewall rules allow necessary connections
  3. Proxy configuration - Check proxy settings if applicable
  4. DNS resolution - Verify DNS resolution for API endpoints
  5. Request timeouts - Increase client-side timeout settings for long-running operations

SSL/TLS Issues ​

Symptoms:

  • SSL handshake failures
  • Certificate errors
  • HTTPS connection problems

Solutions:

  1. Certificate validation - Ensure your environment trusts our SSL certificates
  2. TLS version - Verify you're using TLS 1.2 or higher
  3. CA certificates - Update your CA certificate store
  4. Clock synchronization - Ensure your system clock is accurate

Getting Additional Help ​

If you're still experiencing issues after trying these troubleshooting steps:

  1. Developer Community - Ask questions in our developer forum
  2. Support Tickets - Open a support ticket for persistent issues
  3. Documentation - Check our API reference and guides for detailed information
  4. Status Page - Check our status page for any ongoing service issues

When contacting support, please include:

  • Description of the issue
  • Steps to reproduce
  • Error messages and codes
  • SDK version and environment details
  • Request/response examples (with sensitive data redacted)