# 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` 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` 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.