# How to Handle Rate Limits in Holehe: 6 Proven Solutions

> Overcome Holehe rate limits with 6 proven solutions. Learn to use sleep flags, proxy servers, and exponential back-off to avoid IP blocks and ensure successful email lookups.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```python
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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.