Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Error codes

Errors come back as HTTP status codes on the proxy connection (or the equivalent SOCKS5 reply byte).

CodeMeaningWhat to do
402Data limit reached. Your byte balance is exhaustedTop up. Check with /stats
407Proxy authentication required. Bad or missing credentialsSee below; this is the most commonly misdiagnosed one
417No exit for that location. Nothing matched your targetLoosen the target, or add strict-false
429Too many connections. Account thread cap reachedLower concurrency, or ask for a higher cap
502Upstream failed. A temporary failure on the exit connectionRetry; a new exit is chosen

SOCKS5 equivalents: 0x02 when the data limit or connection cap is reached, 0x04 when no exit matches your target, 0x07 for an unsupported command (e.g. UDP ASSOCIATE), 0x01 for a general or upstream failure.

Debugging 407

A 407 means the credentials we received were not valid. The most common cause is not a wrong password: it is the password being mangled before it ever leaves your machine.

Passwords can contain @, :, /, #, %. Inside a proxy URL those are structural characters, so a parser splits the string in the wrong place and sends the wrong credentials:

# WRONG: the password is parsed as part of the URL
curl -x http://USER:pa@ss/word@proxy.hypercall.dev:4444 https://api.ipify.org

# RIGHT: credentials passed separately, never parsed as a URL
curl -x http://proxy.hypercall.dev:4444 --proxy-user 'USER:pa@ss/word' https://api.ipify.org

# ALSO FINE: quoted, with the password percent-encoded
curl -x 'http://USER:pa%40ss%2Fword@proxy.hypercall.dev:4444' https://api.ipify.org

Work through this order:

  1. Re-test with --proxy-user (or your client’s separate credential fields). If it works, it was a URL-parsing problem, not the password.
  2. Check the account is active. A suspended account returns 407. GET /api/me shows status.
  3. Check source-IP restrictions. If the account has an allowed-ips list, requests from other networks are refused.
  4. Rotate the password if you believe it leaked; see Credentials.

Debugging 417

417 means strict mode found no exit matching your exact target. Either the combination is too narrow (a specific ASN in a specific small city), or coverage for it is momentarily thin.

# Narrow: may return 417
USER-country-us-state-wyoming-city-cody-asn-7922

# Same intent, tolerant of thinner coverage
USER-country-us-state-wyoming-city-cody-asn-7922-strict-false

With strict-false the target widens step by step (asn → city → zip → state) until something matches. Country and session are never dropped.