407 代理身份验证失败

最常见的网关错误——且几乎都是配置问题，而非 helodata 故障。X-Helodata-Error-Code 头细分到具体原因：

auth-failed — 密码错

HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: auth-failed

原因

• 子账号密码错
• 子账号被删除
• 密码被轮换而你的部署仍用旧密码

修复

1. 在 控制台 → {产品} → 子账号 → {名称} 复核密码。
2. 错误则轮换密码并在 60 秒宽限期内更新部署。
3. 子账号已删，请重建。

not-whitelisted — 来源 IP 未授权

HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: not-whitelisted

原因

• 子账号开了 IP 白名单认证，但你的来源 IP 不在清单上。
• 出口 IP 变化（云自动扩缩、换 ISP、NAT 切换）。

修复

1. 查出当前出口 IP：curl https://ipv4.icanhazip.com（不走代理）。
2. 通过 控制台 → {产品} → 子账号 → {名称} → IP 白名单 添加，或：

   curl -X POST -H "Authorization: Bearer API_KEY" \
        -d '{"subuser":"sub_01HX...","product":"residential","ip":"203.0.113.5"}' \
        https://api.helodata.com/v1/whitelists

3. 等 60 秒生效后重试。

bad-username — 用户名无法解析

HTTP/1.1 400 Bad Request
X-Helodata-Error-Code: bad-username

（严格是 400，不是 407，但属同一族。）

原因

• 缺 helo_ 前缀
• 字段顺序错（如 city 在 state 之前）
• 未知字段名（用 -country- 而非 -region-）
• session_id 含非法字符

修复 — 重读 用户名格式。几个常见错：

错	对
helo_s1a2b3c4d5e-region-us-type-res	helo_s1a2b3c4d5e-type-res-region-us
helo_s1a2b3c4d5e-type-res-country-us	helo_s1a2b3c4d5e-type-res-region-us
helo_s1a2b3c4d5e-type-res-region-US	helo_s1a2b3c4d5e-type-res-region-us
helo_s1a2b3c4d5e-type-res-region-us-city-la-state-ca	helo_s1a2b3c4d5e-type-res-region-us-state-ca-city-la
helo_s1a2b3c4d5e-type-res-region-us-session-abc	helo_s1a2b3c4d5e-type-res-region-us-session-abc-sesstime-30

unknown-subuser — 子账号 ID 不存在

HTTP/1.1 401 Unauthorized
X-Helodata-Error-Code: unknown-subuser

原因 — 子账号名笔误，或你用了别的账号下的子账号。

修复 — curl /v1/subusers 列出当前 API Key 对应的正确子账号。

一次性排错

curl -v -x "http://USERNAME:[e-mail]:7777" \
     https://ipv4.icanhazip.com

-v 会显示发送的 Proxy-Authorization 头。常见检查点：

• 密码含特殊字符未 URL 编码
• 端口错（必须 7777——明文 HTTP、SOCKS5、TLS 包裹共用此端口）
• 用户名中粘贴带入了多余空白

仍未解决

邮件 [e-mail] 并附失败请求的 X-Helodata-Request-Id，我们能精确定位哪一步校验失败。