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

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 or 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

The central execution logic resides in 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.

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 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 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, 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.

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