Troubleshooting

Common issues and solutions for FullHunt APIs and platform.

Authentication Issues

401 Unauthorized Error

Problem: Receiving 401 status code when making API requests.

Common Causes:

• Missing or incorrect API key
• Malformed authentication header
• Expired API key

Solutions:

1. Verify your API key is correct
2. Check the authentication header format:

   X-API-KEY: YOUR_API_KEY

3. Ensure there are no extra spaces or characters
4. Try regenerating your API key

403 Forbidden Error

Problem: Receiving 403 status code despite valid authentication.

Common Causes:

• Accessing an endpoint not included in your plan
• Exceeding account permissions
• IP restrictions

Solutions:

1. Check your plan limits in the dashboard
2. Verify the endpoint is available in your subscription
3. Contact support if you believe this is an error

Rate Limiting Issues

429 Too Many Requests

Problem: Receiving rate limit errors.

Common Causes:

• Exceeding your plan's rate limits
• Too many concurrent requests
• Burst traffic patterns

Solutions:

1. Check your current rate limits in the dashboard
2. Implement exponential backoff:

   import time
   import random
   
   def retry_with_backoff(func, max_retries=3):
       for attempt in range(max_retries):
           try:
               return func()
           except RateLimitError:
               if attempt == max_retries - 1:
                   raise
               time.sleep(2 ** attempt + random.uniform(0, 1))

3. Distribute requests over time
4. Consider upgrading your plan for higher limits

Data and Response Issues

Empty or Unexpected Results

Problem: API returns empty results or unexpected data structure.

Common Causes:

• Query parameters not properly formatted
• Requesting data that doesn't exist
• Using incorrect endpoint

Solutions:

1. Verify query parameters are correct
2. Check the API documentation for expected format
3. Test with known good data
4. Validate your request structure

Timeout Errors

Problem: Requests timing out before completion.

Common Causes:

• Network connectivity issues
• Server overload
• Request too complex

Solutions:

1. Increase timeout values in your client
2. Try the request again after a delay
3. Simplify complex queries
4. Check network connectivity

Connection Issues

SSL/TLS Errors

Problem: Certificate or SSL connection errors.

Common Causes:

• Outdated SSL certificates
• Incorrect SSL configuration
• Network proxy issues

Solutions:

1. Update your HTTP client library
2. Verify system certificates are up to date
3. Check proxy settings
4. Try the request from a different network

DNS Resolution Issues

Problem: Unable to resolve fullhunt.io API endpoints.

Common Causes:

• DNS server issues
• Network configuration problems
• Firewall restrictions

Solutions:

1. Try using different DNS servers (8.8.8.8, 1.1.1.1)
2. Check firewall rules
3. Verify network connectivity
4. Contact your IT department if on corporate network

Data Processing Issues

JSON Parse Errors

Problem: Unable to parse API response as JSON.

Common Causes:

• Response is not valid JSON
• Character encoding issues
• Truncated response

Solutions:

1. Check the raw response content
2. Verify Content-Type header
3. Handle potential non-JSON error responses
4. Check for response truncation

Memory Issues with Large Datasets

Problem: Running out of memory when processing large responses.

Common Causes:

• Loading entire response into memory
• Inefficient data processing
• Large result sets

Solutions:

1. Process data in chunks
2. Use streaming JSON parsers
3. Implement pagination
4. Filter results server-side when possible

Common Error Codes

Status Code	Meaning	Common Solutions
400	Bad Request	Check request format and parameters
401	Unauthorized	Verify API key and authentication header
403	Forbidden	Check plan limits and permissions
404	Not Found	Verify endpoint URL and resource existence
429	Too Many Requests	Implement rate limiting and retry logic
500	Internal Server Error	Retry request, contact support if persistent
503	Service Unavailable	Temporary issue, retry with backoff

Debugging Tips

Enable Debug Logging

Add detailed logging to your API client:

import logging
logging.basicConfig(level=logging.DEBUG)

Check Response Headers

Response headers contain useful debugging information:

• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: When rate limit resets
• Content-Type: Response format

Test with curl

Use curl to test requests outside your application:

curl -v -H "X-API-KEY: YOUR_API_KEY" \
  https://fullhunt.io/api/v1/domain/example.com

Getting Additional Help

If these troubleshooting steps don't resolve your issue:

1. Check our FAQ for additional common questions
2. Review the API documentation for specific endpoint details
3. Contact Support with:
   • Complete error message
   • Request/response details
   • Steps to reproduce
   • Your account information

Report a Bug

If you've found a bug in our API:

1. Verify it's reproducible
2. Document the exact steps
3. Include request/response examples
4. Contact our support team with details