# 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 白名单** 添加，或：

   ```bash
   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` 含非法字符

**修复** — 重读 [用户名格式](/helodata-zh/kuai-su-ru-men/username-format.md)。几个常见错：

| 错                                                      | 对                                                             |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| `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 对应的正确子账号。

## 一次性排错

```bash
curl -v -x "http://USERNAME:PASSWORD@gate.helodata.io:7777" \
     https://ipv4.icanhazip.com
```

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

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

## 仍未解决

邮件 <support@helodata.com> 并附失败请求的 `X-Helodata-Request-Id`，我们能精确定位哪一步校验失败。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/gu-zhang-pai-cha/407.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.