限流

helodata 有三层独立限流。识别命中的是哪一层才能正确应对。

1. API 限流

REST API（api.helodata.com）按 API Key 限速：

套餐	突发	日累计
试用	30 / 分	1,000 / 日
Starter	60 / 分	10,000 / 日
Pro	600 / 分	不限
Business	1,200 / 分	不限
Enterprise	定制	定制

响应附标准头：

X-RateLimit-Limit:        600
X-RateLimit-Remaining:    582
X-RateLimit-Reset:        1717029600       # Unix 时间戳

超限返回：

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

2. 网关并发限流

代理网关（gate.helodata.io）按子账号限并发 TCP 连接：

套餐	住宅	移动	ISP
试用	25	10	不适用
Starter	200	50	仅按 IP
Pro	600	200	仅按 IP
Business	2,000	500	仅按 IP
Enterprise	定制	定制	仅按 IP

超限网关返回 429（helodata 码 30002）+ X-Helodata-Error-Code: concurrent-limit，已有连接继续，新连接排队。

ISP IP 没有按子账号并发上限——每个 IP 可承受数百并发 TCP 连接。瓶颈在目标站点而非 helodata。

3. 网关 RPS 限流

与并发不同：每秒可发起多少新请求。

套餐	住宅 RPS	移动 RPS
试用	50	25
Starter	200	100
Pro	1,000	500
Business	3,000	1,500
Enterprise	定制	定制

超限返回 429（helodata 码 30002）+ X-Helodata-Error-Code: rps-limit。带 jitter 重试：

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

退避策略

网关 429 的伪代码：

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                      # 配置错误不重试
    delay = int(resp.headers.get("retry-after", 0)) or (2 ** attempt + random.random())
    time.sleep(min(delay, 30))
    return True

提升上限

子账号上限可通过 PATCH /subusers/{id} 在套餐范围内调整；套餐上限需升级套餐。企业客户支持定制——邮件 [e-mail]。

计数窗口

• API Key：滚动 60 秒（突发）、滚动 24 小时（日）
• 并发：瞬时，连接关闭即恢复
• RPS：滚动 1 秒