Error Handling Guide

Comprehensive guide to understanding, handling, and debugging errors in the Fluence Behavioral Intelligence API. Our enhanced error system provides detailed feedback with actionable solutions to help you build robust integrations.

Quick Troubleshooting

Common Issues & Solutions

Issue	Error Code	Solution
API Key Not Working	401	Check key format, ensure X-API-Key header
Out of Credits	402	Upgrade plan or purchase credits
Profile Not Found	404	Verify name/company spelling, try alternatives
Rate Limited	429	Implement backoff, upgrade plan
Server Error	500	Retry with exponential backoff

Integration Checklist

Error Response Format

All API errors follow a consistent structure with detailed context and actionable guidance:

{
  "success": false,
  "error": {
    "type": "error_category",
    "message": "Human-readable error description",
    "code": 400,
    "user_action": "Specific action user should take",
    "suggestions": [
      "Detailed suggestion 1",
      "Detailed suggestion 2"
    ],
    "confidence_score": 0.3,
    "can_provide_context": true,
    "support_contact": "support@tryfluence.tech"
  },
  "request": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "Microsoft"
  },
  "metadata": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123def456",
    "endpoint": "/analyze",
    "api_version": "2.1.0"
  }
}

HTTP Status Codes

Success Codes

Code	Status	Description
200	OK	Request successful, analysis completed

Client Error Codes (4xx)

Code	Status	Description	Common Causes
400	Bad Request	Invalid request format or parameters	Missing required fields, invalid JSON, wrong data types, batch size exceeded
401	Unauthorized	Authentication failure	Invalid API key, missing x-api-key header
402	Payment Required	Insufficient credits	Credit limit exceeded, insufficient credits for batch
403	Forbidden	Access denied to resource	Tier doesn't include endpoint, plan upgrade required
404	Not Found	Endpoint doesn't exist	Wrong URL or endpoint path
422	Unprocessable Entity	Profile analysis failed	Profile not found or insufficient data
429	Too Many Requests	Rate limit exceeded	Request frequency too high

Server Error Codes (5xx)

Code	Status	Description	Resolution
500	Internal Server Error	Server error during processing	Retry with exponential backoff
503	Service Unavailable	Service temporarily unavailable	Check status page, retry after delay

Common Integration Issues

Tier Access Control Errors

Access Denied (403)

When your API key tier doesn't support a specific endpoint:

{
  "error": "Access denied. Your professional tier API key cannot access /crm_basico. Upgrade to CRM tier for access.",
  "error_code": "ACCESS_DENIED",
  "details": {
    "current_tier": "platform_professional",
    "required_tier": "crm_business",
    "endpoint_requested": "/crm_basico"
  },
  "billing_info": {
    "creditos_utilizados": 0,
    "creditos_restantes": 498,
    "tipo_plano": "platform_professional"
  },
  "upgrade_url": "https://tryfluence.tech/upgrade"
}

Resolution: Upgrade to a CRM tier (Business or Enterprise) to access CRM endpoints.

Credit Refund Policy

Credits are automatically refunded when:

Server errors occur (500 status codes)
Insufficient data found (422 with INSUFFICIENT_DATA)
Request validation fails (400 status codes)
Access denied due to tier restrictions (403)

Application Error Codes

Error Code	Description	Resolution
`INSUFFICIENT_DATA`	Not enough data to analyze profile	Provide more accurate name/company
`PROFILE_NOT_FOUND`	Public profile not found	Verify name and company details
`PROCESSING_ERROR`	Error during analysis	Retry request or contact support
`SERVICE_UNAVAILABLE`	Analysis service unavailable	Wait and retry
`EXTERNAL_SOURCE_ERROR`	External data source unavailable	Retry request
`INSUFFICIENT_CREDITS`	Not enough credits	Purchase credits or upgrade plan
`ACCESS_DENIED`	Tier doesn't support endpoint	Upgrade to required tier

Batch Processing Errors

Insufficient Credits for Batch (402)

When you don't have enough credits for the entire batch:

{
  "error": "Insufficient credits",
  "message": "Batch requires 20 credits but you have 15",
  "profiles_requested": 10,
  "credits_per_profile": 2,
  "credits_available": 15
}

Resolution: Purchase more credits or reduce batch size

Batch Size Exceeded (400)

When batch size exceeds the 10 profile limit:

{
  "error": "Batch size exceeds maximum",
  "message": "Maximum 10 profiles per batch, received 15",
  "max_batch_size": 10,
  "profiles_received": 15
}

Resolution: Split into multiple batches of 10 or fewer

Partial Batch Success (200)

When some profiles succeed and others fail:

{
  "success": true,
  "batch_summary": {
    "total_profiles": 3,
    "successful": 2,
    "failed": 1,
    "processing_time_ms": 8234.56
  },
  "results": [
    {
      "success": true,
      "profile_index": 0,
      "analise": {...}
    },
    {
      "success": false,
      "profile_index": 1,
      "input": {"primeiro_nome": "John", "empresa": "Unknown"},
      "error": "Profile not found",
      "error_code": "PROFILE_NOT_FOUND"
    },
    {
      "success": true,
      "profile_index": 2,
      "analise": {...}
    }
  ],
  "billing_info": {
    "creditos_utilizados": 2,
    "creditos_restantes": 198
  }
}

Note: You're only charged for successful profiles (2 credits in this example)

1. Profile Not Found (404)

Problem: API can't find a matching public professional profile

Solutions:

Check spelling of name and company
Try variations: "Microsoft" vs "MSFT" vs "Microsoft Corporation"
Verify the person has a public professional presence (e.g., LinkedIn)
Use more specific company information
Try the Chrome extension endpoint for basic analysis

Example Fix:

# Instead of:
{"first_name": "John", "last_name": "Smith", "company": "MS"}

# Try:
{"first_name": "John", "last_name": "Smith", "company": "Microsoft Corporation"}

2. Insufficient Digital Footprint (422)

Problem: Limited profile data available for comprehensive analysis

Solutions:

Use CRM Basic endpoint instead of CRM Complete
Provide additional context (job title, location)
Try Chrome extension endpoint for basic analysis
Verify company information is current

3. Rate Limiting (429)

Problem: Too many requests in a short time period

Solutions:

Implement exponential backoff
Upgrade to higher tier plan
Batch requests when possible
Monitor usage in dashboard

4. Authentication Issues (401)

Problem: API key is invalid or missing

Solutions:

Verify API key format and spelling
Ensure using X-API-Key header (not Authorization)
Check if key has expired or been revoked
Generate new key if needed

Error Types & Categories

Authentication Errors

Invalid API Key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": 401,
    "user_action": "Verify your API key is correct and active",
    "suggestions": [
      "Check API key format and spelling",
      "Verify key hasn't expired or been revoked",
      "Ensure using X-API-Key header (not Authorization)"
    ],
    "support_contact": "support@tryfluence.tech"
  }
}

Tier Access Denied

{
  "success": false,
  "error": {
    "type": "access_denied",
    "message": "Access denied. Your professional tier API key cannot access /crm_basico. Upgrade to CRM tier for access.",
    "code": 403,
    "user_action": "Upgrade your plan to access this endpoint",
    "current_tier": "Platform-Users-Professional",
    "required_tier": "CRM-Business-Plan or CRM-Enterprise-Plan",
    "endpoint": "/crm_basico",
    "suggestions": [
      "Upgrade to CRM Business or CRM Enterprise plan",
      "Contact sales for tier upgrade options",
      "Use tier-appropriate endpoints for your plan"
    ],
    "upgrade_contact": "sales@tryfluence.tech"
  }
}

Insufficient Credits

{
  "success": false,
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to complete request",
    "code": 402,
    "credits_needed": 2,
    "credits_available": 0,
    "user_action": "Purchase additional credits or upgrade your plan",
    "upgrade_url": "mailto:support@tryfluence.tech?subject=Credit%20Upgrade%20Request",
    "suggestions": [
      "Purchase credit packages for immediate access",
      "Upgrade to higher monthly plan",
      "Contact sales for enterprise pricing"
    ]
  }
}

Validation Errors

Missing Required Fields

{
  "success": false,
  "error": {
    "type": "validation_error",
    "message": "Required field 'last_name' is missing",
    "code": 400,
    "user_action": "Provide all required fields in request",
    "missing_fields": ["last_name"],
    "required_fields": ["first_name", "last_name", "company"],
    "suggestions": [
      "Check request JSON structure",
      "Verify all required fields are included",
      "Ensure field names match API specification"
    ]
  }
}

Invalid Field Format

{
  "success": false,
  "error": {
    "type": "validation_error",
    "message": "Invalid email format for field 'email'",
    "code": 400,
    "user_action": "Provide valid email address format",
    "invalid_fields": {
      "email": "user@invalid"
    },
    "expected_format": {
      "email": "user@domain.com"
    },
    "suggestions": [
      "Use standard email format (user@domain.com)",
      "Remove special characters from email",
      "Verify email address is complete"
    ]
  }
}

Analysis Errors

Profile Not Found

{
  "success": false,
  "error": {
    "type": "person_not_found",
  "message": "No matching public professional profile found",
    "code": 404,
    "user_action": "Verify person information and try alternative search terms",
    "search_attempts": [
      "John Doe at Microsoft",
      "J. Doe at Microsoft Corp",
      "John D. at MSFT"
    ],
    "suggestions": [
      "Check spelling of name and company",
      "Try variations of company name (Microsoft vs MSFT)",
  "Verify person has a public professional profile",
      "Use more specific company name or department"
    ],
    "confidence_score": 0.0
  }
}

Insufficient Digital Footprint

{
  "success": false,
  "error": {
    "type": "insufficient_digital_footprint",
    "message": "Limited profile data available for comprehensive analysis",
    "code": 422,
    "user_action": "Consider providing additional context or using a different tier",
    "suggestions": [
      "Verify the person's company information",
  "Check for recent public professional activity",
      "Try searching with alternative company names",
      "Use Chrome extension endpoint for basic analysis"
    ],
    "confidence_score": 0.3,
    "can_provide_context": true,
    "available_data": {
      "profile_found": true,
      "recent_activity": false,
      "posts_available": false,
      "complete_profile": false
    }
  }
}

Person Confirmation Required

{
  "success": false,
  "error": {
    "type": "confirmation_required",
    "message": "Multiple potential matches found, confirmation needed",
    "code": 409,
    "user_action": "Review potential matches and specify additional context",
    "potential_matches": [
      {
        "name": "John Doe",
        "title": "Software Engineer",
        "company": "Microsoft Corporation",
        "location": "Seattle, WA",
  "profile_ref": "public_profile_1"
      },
      {
        "name": "John Doe",
        "title": "Product Manager", 
        "company": "Microsoft",
        "location": "Redmond, WA",
  "profile_ref": "public_profile_2"
      }
    ],
    "suggestions": [
      "Specify person's job title or department",
      "Include location information",
      "Use more specific company division",
  "Provide additional disambiguation like department or location"
    ]
  }
}

Rate Limiting Errors

Rate Limit Exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before making another request",
    "code": 429,
    "retry_after": 60,
    "current_limit": "10 requests/second",
    "user_action": "Wait 60 seconds or upgrade to a higher tier for increased limits",
    "rate_limit_info": {
      "requests_made": 65,
      "window_duration": "60 seconds",
      "reset_time": "2025-01-15T11:00:00Z"
    },
    "suggestions": [
      "Implement exponential backoff in your application",
      "Upgrade to Professional or Enterprise plan",
      "Batch requests to reduce frequency",
      "Use Chrome extension endpoint for lightweight analysis"
    ]
  }
}

Service Errors

Temporary Service Issue

{
  "success": false,
  "error": {
    "type": "service_unavailable",
    "message": "Temporary service disruption, please retry",
    "code": 503,
    "user_action": "Retry request after brief delay",
    "estimated_recovery": "2025-01-15T10:45:00Z",
    "suggestions": [
      "Retry request in 5-10 minutes",
      "Implement exponential backoff strategy",
      "Check status page for service updates",
      "Contact support if issue persists"
    ],
    "status_page": "https://status.fluenceinsights.com"
  }
}

Error Handling Best Practices

Retry Strategies

Exponential Backoff Implementation

import time
import random
import requests
from typing import Optional, Dict, Any

class FluenceAPIClient:
    def __init__(self, api_key: str, base_url: str):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        })
    
    def analyze_with_retry(self, data: Dict[str, Any], max_retries: int = 3) -> Optional[Dict]:
        """
        Analyze profile with exponential backoff retry strategy
        """
        for attempt in range(max_retries + 1):
            try:
                response = self.session.post(
                    f"{self.base_url}/analyze",
                    json=data,
                    timeout=30
                )
                
                # Handle successful response
                if response.status_code == 200:
                    return response.json()
                
                # Handle client errors (don't retry)
                if 400 <= response.status_code < 500 and response.status_code != 429:
                    error_data = response.json()
                    print(f"Client error: {error_data['error']['message']}")
                    return None
                
                # Handle rate limiting with specific delay
                if response.status_code == 429:
                    error_data = response.json()
                    retry_after = error_data['error'].get('retry_after', 60)
                    print(f"Rate limited. Waiting {retry_after} seconds...")
                    time.sleep(retry_after)
                    continue
                
                # Handle server errors with exponential backoff
                if response.status_code >= 500:
                    if attempt < max_retries:
                        delay = (2 ** attempt) + random.uniform(0, 1)
                        print(f"Server error. Retrying in {delay:.1f} seconds...")
                        time.sleep(delay)
                        continue
                    else:
                        print("Max retries exceeded for server error")
                        return None
                        
            except requests.exceptions.RequestException as e:
                if attempt < max_retries:
                    delay = (2 ** attempt) + random.uniform(0, 1)
                    print(f"Request failed: {e}. Retrying in {delay:.1f} seconds...")
                    time.sleep(delay)
                    continue
                else:
                    print(f"Max retries exceeded: {e}")
                    return None
        
        return None

# Usage example
client = FluenceAPIClient(
    api_key="your-api-key",
    base_url="https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production"
)

result = client.analyze_with_retry({
    "first_name": "John",
    "last_name": "Doe",
    "company": "Microsoft"
})

if result:
    print("Analysis successful:", result['analysis']['mbti_type'])
else:
    print("Analysis failed after retries")

JavaScript/Node.js Error Handling

const axios = require('axios');

class FluenceAPI {
    constructor(apiKey, baseUrl) {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
        this.client = axios.create({
            baseURL: baseUrl,
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey
            },
            timeout: 30000
        });
    }
    
    async analyzeWithRetry(data, maxRetries = 3) {
        for (let attempt = 0; attempt <= maxRetries; attempt++) {
            try {
                const response = await this.client.post('/analyze', data);
                return response.data;
                
            } catch (error) {
                const { response, code } = error;
                
                // Handle network errors
                if (!response) {
                    if (attempt < maxRetries) {
                        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
                        console.log(`Network error. Retrying in ${delay/1000:.1f} seconds...`);
                        await this.sleep(delay);
                        continue;
                    }
                    throw new Error(`Network error after ${maxRetries} retries: ${error.message}`);
                }
                
                const { status, data: errorData } = response;
                
                // Handle client errors (don't retry)
                if (status >= 400 && status < 500 && status !== 429) {
                    throw new Error(`Client error ${status}: ${errorData.error.message}`);
                }
                
                // Handle rate limiting
                if (status === 429) {
                    const retryAfter = errorData.error.retry_after || 60;
                    console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
                    await this.sleep(retryAfter * 1000);
                    continue;
                }
                
                // Handle server errors
                if (status >= 500) {
                    if (attempt < maxRetries) {
                        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
                        console.log(`Server error ${status}. Retrying in ${delay/1000:.1f} seconds...`);
                        await this.sleep(delay);
                        continue;
                    }
                    throw new Error(`Server error ${status} after ${maxRetries} retries`);
                }
            }
        }
    }
    
    sleep(ms) {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
    
    // Enhanced error handling with specific error types
    async handleSpecificErrors(data) {
        try {
            const result = await this.analyzeWithRetry(data);
            return { success: true, data: result };
            
        } catch (error) {
            // Parse error details if available
            let errorDetails = { type: 'unknown', message: error.message };
            
            try {
                if (error.response && error.response.data && error.response.data.error) {
                    errorDetails = error.response.data.error;
                }
            } catch (parseError) {
                // Ignore parsing errors
            }
            
            // Handle specific error types
            switch (errorDetails.type) {
                case 'insufficient_credits':
                    console.log('Credit issue detected. Consider upgrading plan.');
                    return { 
                        success: false, 
                        error: errorDetails,
                        action: 'upgrade_required'
                    };
                    
                case 'person_not_found':
                    console.log('Profile not found. Try alternative search terms.');
                    return { 
                        success: false, 
                        error: errorDetails,
                        action: 'refine_search'
                    };
                    
                case 'insufficient_digital_footprint':
                    console.log('Limited data available. Try Chrome extension endpoint.');
                    return { 
                        success: false, 
                        error: errorDetails,
                        action: 'use_chrome_extension'
                    };
                    
                case 'confirmation_required':
                    console.log('Multiple matches found. Additional context needed.');
                    return { 
                        success: false, 
                        error: errorDetails,
                        action: 'clarify_person',
                        matches: errorDetails.potential_matches
                    };
                    
                default:
                    return { 
                        success: false, 
                        error: errorDetails,
                        action: 'contact_support'
                    };
            }
        }
    }
}

// Usage with comprehensive error handling
const api = new FluenceAPI(
    process.env.FLUENCE_API_KEY,
    'https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production'
);

async function analyzeProfile(firstName, lastName, company) {
    const result = await api.handleSpecificErrors({
        first_name: firstName,
        last_name: lastName,
        company: company
    });
    
    if (result.success) {
        console.log('Analysis successful:', result.data.analysis.mbti_type);
    } else {
        console.log('Analysis failed:', result.error.message);
        
        // Take specific action based on error type
        switch (result.action) {
            case 'upgrade_required':
                console.log('Redirect user to upgrade page');
                break;
            case 'refine_search':
                console.log('Show suggestions for better search terms');
                break;
            case 'use_chrome_extension':
                console.log('Suggest using Chrome extension endpoint');
                break;
            case 'clarify_person':
                console.log('Show potential matches for user to choose from');
                console.log('Matches:', result.matches);
                break;
            default:
                console.log('Contact support for assistance');
        }
    }
}

Validation Best Practices

Input Validation

import re
from typing import Dict, List, Optional

class RequestValidator:
    @staticmethod
    def validate_analysis_request(data: Dict) -> Dict:
        """
        Validate analysis request data before sending to API
        """
        errors = []
        warnings = []
        
        # Required fields validation
        required_fields = ['first_name', 'last_name', 'company']
        for field in required_fields:
            if not data.get(field):
                errors.append(f"'{field}' is required")
            elif not isinstance(data[field], str):
                errors.append(f"'{field}' must be a string")
            elif len(data[field].strip()) == 0:
                errors.append(f"'{field}' cannot be empty")
        
        # Name validation
        if data.get('first_name'):
            if len(data['first_name']) < 2:
                warnings.append("First name is very short, may affect search accuracy")
            if not re.match(r"^[a-zA-Z\s\-'\.]+$", data['first_name']):
                warnings.append("First name contains unusual characters")
        
        if data.get('last_name'):
            if len(data['last_name']) < 2:
                warnings.append("Last name is very short, may affect search accuracy")
            if not re.match(r"^[a-zA-Z\s\-'\.]+$", data['last_name']):
                warnings.append("Last name contains unusual characters")
        
        # Company validation
        if data.get('company'):
            if len(data['company']) < 2:
                errors.append("Company name is too short")
            
            # Suggest common company name formats
            company_suggestions = []
            company = data['company'].lower()
            if 'microsoft' in company and 'corp' not in company:
                company_suggestions.append("Consider using 'Microsoft Corporation'")
            if 'google' in company and 'inc' not in company:
                company_suggestions.append("Consider using 'Google Inc' or 'Alphabet Inc'")
            
            if company_suggestions:
                warnings.extend(company_suggestions)
        
        # Optional field validation
        if 'language' in data:
            if data['language'] not in ['en', 'pt']:
                errors.append("Language must be 'en' or 'pt'")
        
    # Note: profile URLs are not accepted as input. Do not validate URL fields.
        
        return {
            'valid': len(errors) == 0,
            'errors': errors,
            'warnings': warnings,
            'cleaned_data': RequestValidator._clean_data(data)
        }
    
    @staticmethod
    def _clean_data(data: Dict) -> Dict:
        """Clean and normalize input data"""
        cleaned = {}
        
        for key, value in data.items():
            if isinstance(value, str):
                # Trim whitespace and normalize
                cleaned_value = value.strip()
                
                # Capitalize names properly
                if key in ['first_name', 'last_name']:
                    cleaned_value = ' '.join(word.capitalize() for word in cleaned_value.split())
                
                # Normalize company names
                elif key == 'company':
                    # Common company suffixes
                    suffixes = {
                        ' inc': ' Inc',
                        ' corp': ' Corporation',
                        ' llc': ' LLC',
                        ' ltd': ' Ltd'
                    }
                    for old, new in suffixes.items():
                        if cleaned_value.lower().endswith(old):
                            cleaned_value = cleaned_value[:-len(old)] + new
                
                cleaned[key] = cleaned_value
            else:
                cleaned[key] = value
        
        return cleaned

# Usage example
def safe_analyze_request(api_client, request_data):
    # Validate request before sending
    validation = RequestValidator.validate_analysis_request(request_data)
    
    if not validation['valid']:
        print("Validation errors:")
        for error in validation['errors']:
            print(f"  - {error}")
        return None
    
    if validation['warnings']:
        print("Validation warnings:")
        for warning in validation['warnings']:
            print(f"  - {warning}")
    
    # Use cleaned data for API request
    return api_client.analyze_with_retry(validation['cleaned_data'])

Error Monitoring & Logging

Structured Error Logging

import logging
import json
from datetime import datetime
from typing import Dict, Any

class FluenceErrorLogger:
    def __init__(self, log_file: str = 'fluence_api_errors.log'):
        self.logger = logging.getLogger('fluence_api')
        handler = logging.FileHandler(log_file)
        formatter = logging.Formatter(
            '%(asctime)s - %(levelname)s - %(message)s'
        )
        handler.setFormatter(formatter)
        self.logger.addHandler(handler)
        self.logger.setLevel(logging.INFO)
    
    def log_error(self, error_data: Dict[str, Any], request_data: Dict[str, Any] = None):
        """Log structured error information"""
        log_entry = {
            'timestamp': datetime.utcnow().isoformat(),
            'error': error_data,
            'request': request_data,
            'severity': self._determine_severity(error_data)
        }
        
        self.logger.error(json.dumps(log_entry, indent=2))
    
    def log_success(self, response_data: Dict[str, Any], request_data: Dict[str, Any]):
        """Log successful requests for monitoring"""
        log_entry = {
            'timestamp': datetime.utcnow().isoformat(),
            'status': 'success',
            'request': request_data,
            'response_metadata': response_data.get('metadata', {}),
            'billing_info': response_data.get('billing_info', {})
        }
        
        self.logger.info(json.dumps(log_entry, indent=2))
    
    def _determine_severity(self, error_data: Dict[str, Any]) -> str:
        """Determine error severity level"""
        error_type = error_data.get('type', '')
        status_code = error_data.get('code', 0)
        
        # Critical errors that need immediate attention
        if status_code >= 500:
            return 'critical'
        
        # High priority errors
        if error_type in ['authentication_error', 'insufficient_credits']:
            return 'high'
        
        # Medium priority errors
        if error_type in ['rate_limit_exceeded', 'validation_error']:
            return 'medium'
        
        # Low priority errors (expected business logic)
        if error_type in ['person_not_found', 'insufficient_digital_footprint']:
            return 'low'
        
        return 'medium'

# Usage with error monitoring
logger = FluenceErrorLogger()

def monitored_api_call(api_client, request_data):
    try:
        result = api_client.analyze_with_retry(request_data)
        if result:
            logger.log_success(result, request_data)
            return result
        else:
            logger.log_error(
                {'type': 'unknown_failure', 'message': 'API returned None'},
                request_data
            )
            return None
            
    except Exception as e:
        error_data = {
            'type': 'exception',
            'message': str(e),
            'exception_type': type(e).__name__
        }
        logger.log_error(error_data, request_data)
        raise

Debugging Tools

API Response Inspector

import json
from typing import Dict, Any

class APIResponseInspector:
    @staticmethod
    def inspect_response(response_data: Dict[str, Any], request_data: Dict[str, Any] = None):
        """
        Comprehensive response inspection for debugging
        """
        print("=== API Response Inspector ===")
        
        # Request information
        if request_data:
            print(f"\n📤 Request Data:")
            print(json.dumps(request_data, indent=2))
        
        # Success/Error status
        is_success = response_data.get('success', True)
        print(f"\n✅ Success: {is_success}")
        
        if not is_success:
            # Error analysis
            error = response_data.get('error', {})
            print(f"\n❌ Error Analysis:")
            print(f"   Type: {error.get('type', 'unknown')}")
            print(f"   Code: {error.get('code', 'unknown')}")
            print(f"   Message: {error.get('message', 'No message')}")
            
            # User actions
            if 'user_action' in error:
                print(f"\n🔧 Recommended Action: {error['user_action']}")
            
            # Suggestions
            if 'suggestions' in error:
                print(f"\n💡 Suggestions:")
                for i, suggestion in enumerate(error['suggestions'], 1):
                    print(f"   {i}. {suggestion}")
            
            # Additional context
            if 'confidence_score' in error:
                print(f"\n📊 Confidence Score: {error['confidence_score']}")
            
            if 'potential_matches' in error:
                print(f"\n👥 Potential Matches Found:")
                for i, match in enumerate(error['potential_matches'], 1):
                    print(f"   {i}. {match.get('name')} - {match.get('title')} at {match.get('company')}")
        
        else:
            # Success analysis
            analysis = response_data.get('analysis', response_data.get('analise', {}))
            billing = response_data.get('billing_info', {})
            
            print(f"\n✅ Analysis Successful:")
            if 'mbti_type' in analysis:
                print(f"   MBTI Type: {analysis['mbti_type']}")
            if 'stakeholder_type' in analysis or 'tipo_stakeholder' in analysis:
                stakeholder = analysis.get('stakeholder_type', analysis.get('tipo_stakeholder'))
                print(f"   Stakeholder: {stakeholder}")
            
            if billing:
                print(f"\n💳 Billing Info:")
                print(f"   Credits Used: {billing.get('credits_used', billing.get('creditos_utilizados', 'unknown'))}")
                print(f"   Credits Remaining: {billing.get('credits_remaining', billing.get('creditos_restantes', 'unknown'))}")
                print(f"   Plan Type: {billing.get('plan_type', billing.get('tipo_plano', 'unknown'))}")
        
        # Metadata
        metadata = response_data.get('metadata', {})
        if metadata:
            print(f"\n📋 Metadata:")
            for key, value in metadata.items():
                print(f"   {key}: {value}")
        
        print("\n" + "="*50)

# Usage example
def debug_api_call():
    request_data = {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Microsoft"
    }
    
    # Make API call
    response = api_client.analyze_with_retry(request_data)
    
    # Inspect response for debugging
    APIResponseInspector.inspect_response(response, request_data)
    
    return response

Support & Escalation

When to Contact Support

Contact support@tryfluence.tech for:

Authentication Issues: API key problems, billing discrepancies
Persistent Errors: Repeated 500 errors, service unavailability
Rate Limit Questions: Custom rate limit requirements
Integration Support: Help with specific implementation challenges
Feature Requests: Custom error handling needs

Support Information to Provide

When contacting support, include:

{
  "request_id": "req_abc123def456",
  "timestamp": "2025-01-15T10:30:00Z",
  "api_key_prefix": "bi41LFw9...",
  "endpoint": "/analyze",
  "error_type": "insufficient_digital_footprint",
  "error_code": 422,
  "request_data": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "Microsoft"
  },
  "steps_attempted": [
    "Verified API key format",
    "Tried alternative company names",
    "Implemented retry logic"
  ]
}

Status Page & Updates

Status Page: https://status.fluenceinsights.com
Maintenance Window: Sundays 2-4 AM UTC
SLA: 99.9% uptime for Enterprise plans
Support Hours: 9 AM - 6 PM PST, Monday-Friday

Need help with error handling? Contact support → or test in playground →

Error Handling Guide

Quick Troubleshooting​

Common Issues & Solutions​

Integration Checklist​

Error Response Format​

HTTP Status Codes​

Success Codes​

Client Error Codes (4xx)​

Server Error Codes (5xx)​

Common Integration Issues​

Tier Access Control Errors​

Access Denied (403)​

Credit Refund Policy​

Application Error Codes​

Batch Processing Errors​

Insufficient Credits for Batch (402)​

Batch Size Exceeded (400)​

Partial Batch Success (200)​

1. Profile Not Found (404)​

2. Insufficient Digital Footprint (422)​

3. Rate Limiting (429)​

4. Authentication Issues (401)​

Error Types & Categories​

Authentication Errors​

Invalid API Key​

Tier Access Denied​

Insufficient Credits​

Validation Errors​

Missing Required Fields​

Invalid Field Format​

Analysis Errors​

Profile Not Found​

Insufficient Digital Footprint​

Person Confirmation Required​

Rate Limiting Errors​

Rate Limit Exceeded​

Service Errors​

Temporary Service Issue​

Error Handling Best Practices​

Retry Strategies​

Exponential Backoff Implementation​

JavaScript/Node.js Error Handling​

Validation Best Practices​

Input Validation​

Error Monitoring & Logging​

Structured Error Logging​

Debugging Tools​

API Response Inspector​

Support & Escalation​

When to Contact Support​

Support Information to Provide​

Status Page & Updates​

Quick Troubleshooting

Common Issues & Solutions

Integration Checklist

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes (4xx)

Server Error Codes (5xx)

Common Integration Issues

Tier Access Control Errors

Access Denied (403)

Credit Refund Policy

Application Error Codes

Batch Processing Errors

Insufficient Credits for Batch (402)

Batch Size Exceeded (400)

Partial Batch Success (200)

1. Profile Not Found (404)

2. Insufficient Digital Footprint (422)

3. Rate Limiting (429)

4. Authentication Issues (401)

Error Types & Categories

Authentication Errors

Invalid API Key

Tier Access Denied

Insufficient Credits

Validation Errors

Missing Required Fields

Invalid Field Format

Analysis Errors

Profile Not Found

Insufficient Digital Footprint

Person Confirmation Required

Rate Limiting Errors

Rate Limit Exceeded

Service Errors

Temporary Service Issue

Error Handling Best Practices

Retry Strategies

Exponential Backoff Implementation

JavaScript/Node.js Error Handling

Validation Best Practices

Input Validation

Error Monitoring & Logging

Structured Error Logging

Debugging Tools

API Response Inspector

Support & Escalation

When to Contact Support

Support Information to Provide

Status Page & Updates