# What Does `frequent_rate_limit=True` Mean in Holehe Modules?

> Understand frequent_rate_limit=True in Holehe modules. Learn how it handles HTTP 429 errors, implements cooldowns, and retries requests for reliable email enumeration on rate-limited platforms.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: internals
- Published: 2026-09-10

---

**Setting `frequent_rate_limit=True` tells a Holehe service module to detect HTTP 429 responses, pause execution for a cooldown period, and retry the request rather than immediately failing, ensuring reliable email enumeration against strictly rate‑limited platforms.**

Holehe is an open‑source email reconnaissance framework developed by megadose that checks whether an address is registered on hundreds of websites. When invoking individual checker modules—such as those found in [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py) or [`holehe/modules/software/docker.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/docker.py)—the `frequent_rate_limit` parameter controls how the tool reacts to aggressive rate‑limiting policies employed by target services.

## Core Orchestration in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)

The central execution logic resides in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), where the `launch_module` function wraps each service check and manages exception handling. When a module encounters a rate limit, it returns a dictionary containing the key **`"rateLimit": True`**. The core detects this flag (around lines 71‑75 in the source) and passes it to `print_result` (lines 23‑27), which renders a **yellow `[x]` indicator** in the CLI output. This visual distinction separates temporary blocks from definitive “account not found” or error states, allowing operators to identify which services require later re‑checking.

## Module‑Level Rate Limit Logic

Each async function inside a service module accepts the parameter `frequentratelimit` (the lowercase implementation of the flag) to toggle defensive behavior. The boolean value determines whether the module implements sleep delays and retry loops when receiving HTTP 429 “Too Many Requests” responses.

### Defensive Mode (`frequentratelimit=True`)

When the parameter is set to **`True`**, the module executes the following workflow:

- **Detects** HTTP 429 status codes or custom rate‑limit headers returned by the target
- **Pauses** execution using `trio.sleep()` or similar async delays between retry attempts
- **Retries** the request up to a predefined limit before giving up
- **Marks** the final result with `"rateLimit": True` so the core displays the yellow warning indicator

This mode is essential for platforms like Twitter or Instagram that enforce strict request throttling, preventing immediate IP bans during large‑scale enumeration.

### Aggressive Mode (`frequentratelimit=False`)

Setting the flag to **`False`** disables all retry logic:

- The module **fails fast** upon receiving any 429 response
- **No sleep delays** are inserted between requests
- The result is reported as a hard error rather than a temporary rate limit

While this approach increases scanning speed, it significantly raises the risk of permanent blocks and missed data when encountering protected endpoints.

## Practical Implementation Examples

When calling Holehe modules programmatically, you can override the default defensive behavior by passing the `frequentratelimit` argument explicitly. The standard signature for module functions accepts `email`, `http_client`, `out` (the result collector), and the rate‑limit flag.

```python
import holehe.modules.social_media.twitter as twitter_checker
import trio

async def enumerate_email(email, http_client):
    # Default defensive behavior: handle rate limits gracefully

    result = await twitter_checker(
        email, 
        http_client, 
        out=None, 
        frequentratelimit=True
    )
    
    # Aggressive scanning: skip retries (higher block risk)

    result_fast = await twitter_checker(
        email, 
        http_client, 
        out=None, 
        frequentratelimit=False
    )
    
    return result

```

In the standard CLI execution path, `launch_module` in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) automatically manages the `out` dictionary and exception catching, ensuring that the `rateLimit` boolean returned by the module is processed correctly according to the `frequentratelimit` setting provided.

## Summary

- **`frequent_rate_limit=True`** enables defensive rate‑limit handling that pauses and retries requests upon receiving HTTP 429 responses
- The core framework in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) interprets the `"rateLimit"` key in result dictionaries to display yellow `[x]` indicators for temporarily blocked services
- Individual modules implement the specific retry logic, while the `launch_module` wrapper orchestrates error handling and reporting
- Setting the flag to `False` increases scanning speed but risks immediate IP bans from protected platforms like Twitter and Docker Hub
- Most modules default to `True` to maximize data collection success across rate‑limited infrastructure

## Frequently Asked Questions

### Is `frequent_rate_limit` enabled by default in Holehe modules?

Yes, the majority of modules in the megadose/holehe repository default to `frequentratelimit=True` to ensure reliable enumeration. This defensive setting prevents immediate IP bans when checking email addresses against heavily protected services, though it may slow down the overall scan compared to aggressive mode.

### How does Holehe display rate‑limited services in the terminal output?

According to the source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), the `print_result` function checks for the `"rateLimit"` key in the module’s return dictionary. When this value is `True`, the function renders a **yellow `[x]`** symbol next to the service name, visually distinguishing temporary blocks from red error states or green confirmation marks.

### What happens when a module hits a rate limit with the flag set to `True`?

When `frequentratelimit=True` and a module encounters an HTTP 429 response, it enters a cooldown loop, sleeping for several seconds before retrying the request. If the limit persists after multiple attempts, the module returns `"rateLimit": True`, which the core displays as a yellow warning rather than a hard failure, indicating the check should be retried later with fresh proxies or a different IP.

### Can I disable rate limit handling to speed up my scan?

While you can set `frequentratelimit=False` to skip retry delays and fail immediately on 429 responses, this is **not recommended** for production OSINT work. Disabling the flag causes instant failure on protected endpoints and dramatically increases the risk of permanent IP blocks, ultimately reducing your successful enumeration rate across rate‑limited platforms.