How to Handle Rate Limits in Holehe: 6 Proven Solutions

When you encounter rate limits while using Holehe, configure the --sleep flag to insert delays between module requests, use -m to limit active services and reduce request volume, route traffic through --proxy servers to rotate IP addresses, or wrap the CLI in a Python script that parses the rateLimit JSON flag and implements exponential back-off.

Holehe is an open-source OSINT tool developed by megadose that checks if email addresses are registered across hundreds of social media, shopping, and email platforms. Because it queries services in rapid succession, you will inevitably hit holehe rate limit restrictions that return HTTP 429 responses or temporary blocks. Understanding how Holehe's architecture detects these limits and which CLI flags mitigate them is essential for uninterrupted reconnaissance.

Understanding Rate Limit Detection in Holehe

According to the megadose/holehe source code, each service module under holehe/modules/ returns a standardized dictionary containing a rateLimit boolean flag and a frequent_rate_limit indicator. The orchestration logic in holehe/core.py consumes these values during execution; when a module sets rateLimit: true, Holehe immediately halts further requests to that endpoint for the current run. This prevents wasted bandwidth and reduces the risk of IP bans. The CLI parsing logic in holehe/instruments.py exposes the throttling options documented below.

Insert Delays Between Requests (--sleep)

To avoid triggering rate limits, add the --sleep flag followed by the number of seconds to pause between module executions. This is the simplest method to reduce request velocity and allow remote APIs to reset their counters.

holehe -i user@example.com --sleep 60

This command pauses 60 seconds between each service query, effectively lowering your request rate below the threshold that triggers HTTP 429 errors.

Reduce Request Volume with Module Selection (-m)

Instead of scanning all available services, use the -m or --module flag to target only specific platforms. This significantly lowers the total number of HTTP requests generated during a single run, reducing the probability of hitting provider-specific limits.

holehe -i user@example.com -m instagram -m linkedin

By checking only Instagram and LinkedIn, you minimize the chance of triggering limits on high-frequency services while maintaining fast execution and focused results.

Rotate IP Addresses with Proxies (--proxy)

When running systematic scans or repeated checks against the same targets, use the --proxy flag to route traffic through alternate IP addresses. This bypasses per-IP rate limits imposed by services that track request velocity by source address.

holehe -i user@example.com --proxy http://127.0.0.1:9050

For Tor users, configure the proxy to route through the local SOCKS5 port to distribute requests across the Tor network, effectively obtaining a new exit node for each connection.

Enable Automatic Retries (--retry)

For transient rate limits that lift quickly, enable the built-in retry mechanism using the --retry flag followed by the number of attempts. This setting automatically re-executes failed modules when they return rate-limit flags.

holehe -i user@example.com --retry 3

This approach is useful for handling sporadic HTTP 429 responses without manual intervention, as Holehe will pause briefly before retrying the specific module that failed.

Implementing Exponential Back-Off in Python

For granular control over retry logic and back-off timing, wrap Holehe in a Python script that parses the JSON output for the rateLimit flag and implements exponential back-off. This method is ideal for integration into automated pipelines where you need intelligent waiting periods.

import time, subprocess

for attempt in range(5):
    result = subprocess.run(
        ["holehe", "-i", "user@example.com"],
        capture_output=True
    )
    if b'"rateLimit": true' not in result.stdout:
        break
    wait = 2 ** attempt
    print(f"Rate limit hit – waiting {wait}s")
    time.sleep(wait)

This script doubles the wait time after each failure, respecting the service's cooling-off period before subsequent attempts and ensuring you do not overwhelm the target API.

Respecting Service Headers and Execution Frequency

Some modules in holehe/modules/ implement logic to read official rate-limit headers such as X-RateLimit-Reset and pause execution until the specified reset time. Review the module source—for example, holehe/modules/social_media/twitter.py—to verify if it handles these headers via the frequent_rate_limit indicator. Additionally, reduce the overall execution frequency of Holehe by running scans daily rather than hourly to prevent accumulating long-term blocks on your source IP.

Summary

• Configure --sleep to add constant delays between individual module requests
• Use -m flags to narrow the scope to specific services, minimizing total HTTP requests
• Route connections through --proxy servers to circumvent IP-based restrictions
• Enable --retry for automatic handling of transient HTTP 429 errors
• Parse the rateLimit boolean in JSON output to implement custom exponential back-off loops
• Review module-specific logic in holehe/core.py and holehe/instruments.py for advanced throttling options

Frequently Asked Questions

How does Holehe indicate that a service has rate-limited the request?

Holehe modules return a JSON object containing a rateLimit boolean field set to true when the service returns an HTTP 429 or similar restriction. The frequent_rate_limit indicator in the module metadata—registered in holehe/modules/__init__.py—also signals that this service is historically prone to strict throttling policies.

Can I use Tor as a proxy to avoid rate limits?

Yes. Use the --proxy flag with your Tor SOCKS5 port (typically http://127.0.0.1:9050 or socks5h://127.0.0.1:9050) to route requests through the Tor network. This rotates your exit IP address between requests, effectively bypassing per-IP rate limits imposed by target platforms.

What is the difference between rateLimit and frequent_rate_limit?

The rateLimit flag indicates an active block received during the current execution, while frequent_rate_limit is a static metadata property defined in individual service modules that marks platforms known for aggressive rate limiting regardless of current status. Check holehe/core.py to see how the orchestrator uses these values to skip redundant calls.

Does Holehe automatically respect the X-RateLimit-Reset header?

Some modules implement logic to parse headers like X-RateLimit-Reset and pause execution until the specified Unix timestamp. However, implementation varies by service; you must check the specific module source code under holehe/modules/ to determine if it handles these reset headers or relies solely on the rateLimit boolean flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}