错误说明

网关同时返回 HTTP 状态码、数字 helodata 码 与 X-Helodata-Error-Code 头，后者精确指明原因。重试前请结合三者判断。

网关层错误（helodata 产生）

状态码	helodata 码	X-Helodata-Error-Code	含义	处理
400	20002	bad-username	用户名不符合语法	复核 用户名格式
400	20002	unknown-region	国家代码不识别	使用 ISO-3166 alpha-2
400	20002	state-without-region	有 state 但缺 region	补充 region
400	20002	city-without-state	有 city 但缺 state	补充 state
400	20002	session-incomplete	session 与 sesstime 未成对出现	二者必须同时存在
400	20002	sesstime-out-of-range	TTL 超 30（住宅）	减小 sesstime
401	20003	unknown-subuser	子账号不存在	在控制台核对
403	—	restricted-category-*	目标被屏蔽，详见 受限站点	申请例外
403	—	account-suspended	账号因计费或滥用被冻结	联系客服
407	20003	auth-failed	密码错误	核对，必要时轮换
407	20003	not-whitelisted	来源 IP 不在白名单	在控制台添加
429	30002	concurrent-limit	并发连接超限	限流或升级套餐
429	30002	rps-limit	每秒请求超限	带 jitter 退避重试
502	40001	pool-empty	池中无匹配 IP	放宽地理/ASN 筛选
502	40001	upstream-tls-error	目标 TLS 握手失败	详见 SSL 错误
522	—	upstream-timeout	后端 IP 不可达	重试，多为瞬时
522	—	insufficient-pool	组合筛选后在线 IP 不足 10	放宽筛选
524	—	target-timeout	目标站点超时未响应	重试或加大客户端超时

目标层错误（直通）

目标站点返回的错误由 helodata 原样透传。出现以下响应头即说明代理成功，问题在下游：

X-Helodata-Exit-IP: 198.51.100.42
X-Helodata-Exit-Geo: us/ca/la
X-Helodata-Exit-ASN: 7922

如果带着这些头同时收到目标的 403，那是目标本身拒绝了该 IP，不是 helodata。

常见直通状态码

状态码	常见原因	缓解
目标返回 403	反爬系统拒绝该 IP	轮换 IP、补请求头、降速
目标返回 429	被目标限流	单 IP 降速、增加轮换
目标返回 503	目标过载	退避重试
Cloudflare 1020 页	地理或指纹被识破	加请求头、用粘性会话、换国家

重试策略

按下表区分对待，不同错误应对方式不同：

RETRYABLE_GATEWAY = {429, 502, 522, 524}

def should_retry(status, err_code):
    if status in (400, 401, 403, 407):
        return False                          # 配置问题，重试无意义
    if status in RETRYABLE_GATEWAY:
        return True
    return False

rps-limit 类 429，带 1–5 秒 jitter；pool-empty 只有在放宽筛选后才重试。

日志建议

每次请求都记录 status、X-Helodata-Error-Code、X-Helodata-Exit-IP 三元组。绝大多数「出了什么问题」的复盘无需重跑就能定位。