# 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.


---

# 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/troubleshooting/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.