错误码总览

请求失败时，三个信号告诉你问题在哪。按以下顺序读：

1. HTTP 状态码 — 粗类别（认证、限流、上游、目标）
2. X-Helodata-Error-Code 响应头 — 精确原因（仅网关原产的错误带）
3. X-Helodata-Request-Id — 寻求客服支持时附上

一行粘贴的日志胜过千次猜测。

速查

状态码	helodata 码	最可能原因	首查页面
400	20002	用户名语法错	用户名格式
401 / 407	20003	凭证错 / IP 未加入白名单	407 代理身份验证失败
403	—	受限目标或未通过 KYC	X-Helodata-Error-Code 与 受限站点
429	30002	触发限流	限流
502	40001	IP 池耗尽、TLS 问题	SSL / TLS 错误、放宽用户名筛选
522	—	上游超时	522 连接超时
524	—	目标响应慢	目标慢，重试或调大客户端超时
Cloudflare 1020 页	—	被识破地理或指纹	验证码、IP 地理位置不匹配

如何读一个失败请求

真实示例：

HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: not-whitelisted
X-Helodata-Request-Id: req_01HX2K3PQ4M5
Content-Type: application/json

{"code":"not-whitelisted","message":"Source IP 203.0.113.5 isn't on the whitelist for sub-user sub_01HX..."}

要抓取三件事：

• 状态 407 → 认证类
• not-whitelisted → 来源 IP 不在该子账号白名单
• req_01HX2K3PQ4M5 → 保存好，找客服时我们可凭它定位这次调用

常见现象

你看到的	多半原因	跳转
首请求总返回 407	用户名语法或密码错	407
在城市级筛选下随机 522	IP 池过小	522
部分站点 OK，部分 SSL 错	目标 TLS 配置异常或 CA 证书库过期	SSL/TLS 错误
某国家大量验证码	指纹不匹配或池烧毁	验证码
Exit-IP 地理判错	MaxMind 库延迟	IP 地理位置不匹配
响应时间 5–10 秒	移动 / 反爬延迟	速度过慢
页面就是不渲染	JS 重的站点或被屏蔽	网站打不开

错误信号读不懂时

记录 状态码 + X-Helodata-Error-Code + X-Helodata-Request-Id 三元组并发邮件至 [e-mail]。Request-Id 在调用后 7 天内可用于检索完整请求记录。

各产品错误码表

完整代码表在各产品参考页：

• 住宅错误说明
• 移动错误说明
• ISP 错误说明