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:

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

curl -v -x "http://USERNAME:[e-mail]: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 [e-mail] with the X-Helodata-Request-Id from a failed call. We can see exactly which check failed.