Common Errors and Troubleshooting

This document provides solutions for common errors and issues you might encounter when using the InsightEmbed widget and API.

Widget Installation Issues

Widget Not Appearing

Problem: The widget is not visible on your website after installation.

Possible Causes and Solutions:

1. Incorrect API Key

   • Verify that you're using a Widget API Key (not a Primary API Key)
   • Check that the API key is valid and not revoked in the Management Portal

2. Domain Restrictions

   • Ensure your website's domain is included in the allowed domains list for your Widget API Key
   • For local development, add localhost to the allowed domains

3. JavaScript Errors

   • Check your browser's console for JavaScript errors
   • Ensure the widget script is loading correctly
   • Verify that there are no JavaScript conflicts with other libraries

4. Content Security Policy (CSP)

   • If your site uses a Content Security Policy, ensure it allows:
     • Script source: cdn.insightembed.com
     • Connect source: api.insightembed.com
     • Frame source: cdn.insightembed.com

5. Visibility Settings

   • Check if the widget is configured to be hidden based on URL patterns or other visibility settings
   • Try explicitly showing the widget using JavaScript: InsightEmbed.show()

Widget Loads But Doesn't Function

Problem: The widget appears on your website but doesn't respond to interactions.

Possible Causes and Solutions:

1. Initialization Issues

   • Ensure the widget is fully initialized before interaction
   • Check for initialization errors in the browser console
   • Try reinitializing the widget with basic settings

2. Quota Exceeded

   • Verify that you haven't exceeded your monthly analysis quota
   • Check your usage in the Management Portal

3. JavaScript Conflicts

   • Test the widget on a minimal page to rule out conflicts with other scripts
   • Ensure no other scripts are capturing the events the widget relies on

API Authentication Errors

401 Unauthorized

Problem: API requests return a 401 Unauthorized error.

Possible Causes and Solutions:

1. Invalid API Key

   • Verify that the API key is correct and active
   • Check for typos or extra spaces in the API key

2. Incorrect Authentication Format

   • Ensure you're using the correct format: Authorization: Bearer YOUR_API_KEY
   • Check that "Bearer" is included and spelled correctly

3. Using Wrong Key Type

   • Confirm you're using a Primary API Key for server-side API calls
   • Widget API Keys have limited permissions and can't access all endpoints

403 Forbidden

Problem: API requests return a 403 Forbidden error.

Possible Causes and Solutions:

1. Domain Not Allowed

   • For Widget API Keys, check that the request origin is in the allowed domains list
   • Verify the exact domain format (including subdomains)

2. Insufficient Permissions

   • Verify that your subscription plan includes access to the requested feature
   • Check if you're trying to access a Pro feature with a Free or Starter plan

3. Account Suspension

   • Check if your account has been suspended due to payment issues or terms violations
   • Contact support if you believe this is in error

Analysis Errors

Text Analysis Fails

Problem: Text analysis requests fail or return errors.

Possible Causes and Solutions:

1. Content Too Large

   • Check if the text exceeds the maximum size limit for your plan
   • Try breaking the content into smaller chunks

2. Invalid Content Format

   • Ensure the text is properly encoded (UTF-8)
   • Remove any invalid or special characters

3. API Quota Exceeded

   • Verify that you haven't exceeded your monthly analysis quota
   • Consider upgrading your plan or purchasing additional quota

Image Analysis Fails

Problem: Image analysis requests fail or return errors.

Possible Causes and Solutions:

1. Unsupported Image Format

   • Ensure you're using a supported format (JPEG, PNG, GIF, BMP, WEBP, HEIC/HEIF)
   • Convert the image to a supported format if necessary

2. Image Too Large

   • Check if the image exceeds the maximum file size for your plan
   • Resize or compress the image to reduce its size

3. Invalid Image Data

   • Verify that the image file isn't corrupted
   • Ensure the image URL is accessible if using URL-based analysis

Screenshot Capture Fails

Problem: Screenshot capture functionality doesn't work.

Possible Causes and Solutions:

1. Browser Permissions

   • Ensure the user has granted screen capture permissions
   • Some browsers require HTTPS for screen capture functionality

2. Browser Compatibility

   • Verify that the user's browser supports the Screen Capture API
   • Provide fallback options for unsupported browsers

3. Extension Conflicts

   • Check if browser extensions are interfering with screen capture
   • Test in incognito/private mode to rule out extension conflicts

Rate Limiting and Quota Issues

429 Too Many Requests

Problem: API requests return a 429 Too Many Requests error.

Possible Causes and Solutions:

1. Rate Limit Exceeded

   • Reduce the frequency of API calls
   • Implement exponential backoff for retries
   • Check your plan's rate limits in the API documentation

2. Concurrent Request Limit

   • Ensure you're not making too many simultaneous requests
   • Implement request queuing if necessary

Quota Exceeded

Problem: You've reached your monthly analysis quota limit.

Possible Causes and Solutions:

1. High Usage

   • Review your usage patterns in the Analytics dashboard
   • Identify any unexpected spikes in usage

2. Upgrade Options

   • Consider upgrading to a higher tier plan
   • Purchase additional quota for the current month

3. Optimize Usage

   • Implement caching for repeated analyses
   • Use batch endpoints for multiple analyses
   • Set appropriate visibility rules to prevent unnecessary widget usage

Widget Configuration Issues

Custom Theme Not Applied

Problem: Custom theme settings aren't reflected in the widget appearance.

Possible Causes and Solutions:

1. Initialization Order

   • Ensure theme settings are provided during initial widget initialization
   • If updating theme after initialization, use the updateTheme() method

2. Invalid Color Formats

   • Verify that color values are in valid formats (hex, rgb, rgba)
   • Check for typos in color codes

3. CSS Conflicts

   • Inspect the widget elements to check if other CSS rules are overriding your theme
   • Use more specific selectors in your custom CSS

Widget Position Issues

Problem: The widget appears in the wrong position or is cut off.

Possible Causes and Solutions:

1. Conflicting Positioning

   • Check if other fixed elements on your page are conflicting with the widget
   • Adjust the widget's z-index or position settings

2. Responsive Layout Issues

   • Test on different screen sizes and devices
   • Configure responsive positioning settings for different breakpoints

3. Iframe or Container Constraints

   • If your site uses iframes, ensure the widget is initialized in the correct context
   • Check if the widget is constrained by an overflow: hidden container

Browser Compatibility Issues

Widget Doesn't Work in Specific Browsers

Problem: The widget functions in some browsers but not others.

Possible Causes and Solutions:

1. Unsupported Browser

   • Check the Browser Compatibility guide for supported browsers
   • Consider adding a fallback experience for unsupported browsers

2. Browser Extensions

   • Test in incognito/private mode to rule out extension conflicts
   • Identify specific extensions that might be blocking functionality

3. Feature Detection

   • Implement feature detection rather than browser detection
   • Provide graceful degradation for missing features

Network and Connectivity Issues

API Timeouts

Problem: API requests time out or take too long to complete.

Possible Causes and Solutions:

1. Server Load

   • The API might be experiencing high load; implement retry logic with backoff
   • Consider using batch endpoints to reduce the number of requests

2. Network Issues

   • Check the user's internet connection
   • Implement proper error handling for network failures

3. Large Payloads

   • Reduce the size of request payloads
   • Optimize image sizes before uploading

CORS Errors

Problem: Cross-Origin Resource Sharing (CORS) errors in the browser console.

Possible Causes and Solutions:

1. Domain Not Allowed

   • Ensure your domain is properly configured in the API key settings
   • Check for protocol mismatches (http vs https)

2. Proxy Requests

   • For server-to-server communication, make requests from your backend to avoid CORS issues
   • Set up a proxy endpoint on your server if necessary

Account and Billing Issues

Payment Failure

Problem: Subscription payment fails or card is declined.

Possible Causes and Solutions:

1. Card Issues

   • Verify card details and expiration date
   • Check if the card has sufficient funds or credit
   • Contact your bank to authorize the transaction

2. Billing Information

   • Ensure your billing information is up to date
   • Verify that the billing address matches the card's registered address

3. Alternative Payment

   • Try an alternative payment method
   • Contact support for assistance with payment issues

Getting Additional Help

If you're still experiencing issues after trying the solutions above:

1. Check Documentation

   • Review the relevant sections of the documentation for more detailed guidance
   • Look for recent updates in the Changelog

2. Community Forums

   • Search the community forums for similar issues and solutions
   • Post your question with detailed information about the problem

3. Contact Support

   • Submit a support ticket through the Management Portal
   • Include detailed information about the issue, steps to reproduce, and any error messages
   • For Pro plan subscribers, use the priority support channel

4. Live Chat

   • Pro plan subscribers can access live chat support during business hours
   • Navigate to the Support section in the Management Portal to access live chat

Reporting Bugs

If you believe you've found a bug in the InsightEmbed platform:

1. Check if the issue is already known in the Changelog or community forums
2. Gather detailed information about the bug, including:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Browser and device information
   • Screenshots or videos if applicable
3. Submit a bug report through the Management Portal or email support@insightembed.com

We appreciate your help in improving InsightEmbed for all users!