> 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