> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/rate-limits.md).

# Rate limits

helodata enforces three independent layers of rate limiting. Know which one you hit so you can react correctly.

## 1. API rate limits

The REST API (`api.helodata.com`) caps requests per API key:

| Plan       | Burst       | Sustained    |
| ---------- | ----------- | ------------ |
| Trial      | 30 / min    | 1,000 / day  |
| Starter    | 60 / min    | 10,000 / day |
| Pro        | 600 / min   | unlimited    |
| Business   | 1,200 / min | unlimited    |
| Enterprise | custom      | custom       |

Responses include the standard headers:

```
X-RateLimit-Limit:        600
X-RateLimit-Remaining:    582
X-RateLimit-Reset:        1717029600       # Unix epoch
```

Over the limit returns:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 8
{"code":"rate_limited","message":"API rate limit exceeded","request_id":"req_01HX..."}
```

## 2. Gateway concurrent limits

The proxy gateway (`gate.helodata.io`) caps concurrent TCP connections per sub-user:

| Plan       | Residential | Mobile | ISP         |
| ---------- | ----------- | ------ | ----------- |
| Trial      | 25          | 10     | n/a         |
| Starter    | 200         | 50     | per-IP only |
| Pro        | 600         | 200    | per-IP only |
| Business   | 2,000       | 500    | per-IP only |
| Enterprise | custom      | custom | per-IP only |

Over the limit, the gateway returns `429` (helodata code `30002`) with `X-Helodata-Error-Code: concurrent-limit`. Existing connections continue; new ones wait.

ISP IPs have no per-sub-user concurrency cap — each IP can handle hundreds of concurrent TCP connections. The bottleneck is the target site, not us.

## 3. Gateway requests-per-second limits

Distinct from concurrency: how many *new* requests you can fire each second.

| Plan       | Residential RPS | Mobile RPS |
| ---------- | --------------- | ---------- |
| Trial      | 50              | 25         |
| Starter    | 200             | 100        |
| Pro        | 1,000           | 500        |
| Business   | 3,000           | 1,500      |
| Enterprise | custom          | custom     |

Over the limit returns `429` (helodata code `30002`) with `X-Helodata-Error-Code: rps-limit`. Retry with jitter:

```python
import time, random
time.sleep((2 ** attempt) * 0.1 + random.random())
```

## Backoff strategy

Pseudo-code for any 429 from the gateway:

```python
RETRYABLE = {"rps-limit", "concurrent-limit"}

def on_429(resp, attempt):
    err = resp.headers.get("x-helodata-error-code")
    if err not in RETRYABLE:
        return False                      # don't retry config errors
    delay = int(resp.headers.get("retry-after", 0)) or (2 ** attempt + random.random())
    time.sleep(min(delay, 30))
    return True
```

## Raising limits

Per-sub-user limits can be raised within plan limits via `PATCH /subusers/{id}`. Plan-level limits require upgrading. Enterprise customers get custom limits — email <sales@helodata.com>.

## Counters reset

* API key: rolling 60-second window (burst), rolling 24-hour window (daily)
* Concurrent: instantaneous; recovers as soon as connections close
* RPS: rolling 1-second window


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.helodata.com/api-reference/rate-limits.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.