> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/troubleshooting/407.md).

# 407 Proxy Authentication Required

The most common gateway error — and almost always a config issue, not a helodata fault. The `X-Helodata-Error-Code` header tells you which kind:

## `auth-failed` — wrong password

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

**Causes**

* Sub-user password is wrong
* Sub-user was deleted
* Password was rotated and your deployment still has the old one

**Fix**

1. Verify the password in **Dashboard → {Product} → Sub-users → {name}**.
2. If wrong, rotate the password and update your deployment within the 60-second grace window.
3. If the sub-user is gone, recreate it.

## `not-whitelisted` — source IP not authorized

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

**Causes**

* You configured the sub-user to require IP whitelisting and your source IP isn't on the list.
* Your egress IP changed (cloud autoscale, new ISP, NAT switch).

**Fix**

1. Find your current egress IP: `curl https://ipv4.icanhazip.com` (without the proxy).
2. Add it to the whitelist via **Dashboard → {Product} → Sub-users → {name} → Whitelisted IPs**, or:

   ```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. Wait up to 60 seconds for propagation, then retry.

## `bad-username` — username doesn't parse

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

(Strictly 400, not 407, but conceptually the same family.)

**Causes**

* Missing `helo_` prefix
* Misordered segments (e.g. `city` before `state`)
* Unknown segment names (`-country-` instead of `-region-`)
* Bad characters in `session_id`

**Fix** — re-read [Username format](/getting-started/username-format.md). A few common mistakes:

| Wrong                                                  | Right                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| `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` — sub-user ID doesn't exist

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

**Cause** — typo in the sub-user name, or you're using a sub-user from a different account.

**Fix** — `curl /v1/subusers` to list the right ones for your API key.

## How to debug 407 once

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

`-v` shows the `Proxy-Authorization` header that's being sent. Common things to spot:

* Special characters in password that weren't URL-encoded
* Wrong port (must be `7777` — works for plain HTTP, SOCKS5, and TLS-wrapped)
* Extra whitespace in username from a copy-paste

## Still stuck

Email <support@helodata.com> with the `X-Helodata-Request-Id` from a failed call. We can see exactly which check failed.