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:

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

Backoff strategy

Pseudo-code for any 429 from the gateway:

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 [e-mail].

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