Proxy error codes
What each status code from the gateway means, what usually causes it, and what to change.
When the gateway itself cannot serve a request it answers with one of the status codes below and a JSON body that says why, {"error":{"code":"…","message":"…"}}: the same shape as the REST API's errors. Anything else, including a 403 or 429 from the site you are fetching, came from the destination and passed through untouched. A request the gateway cannot read, or that takes longer than 10 seconds to authenticate, is closed without an answer, and an open tunnel that runs out of traffic or loses its proxy user is simply closed.
407 Proxy Authentication Required
The gateway could not match the connection to a proxy user. Common causes:
- Wrong password, or a password that was rotated.
- The
handle-namepart of the username does not match a proxy user on your account. - A targeting parameter is misspelt or has a value the gateway does not serve, such as a country other than
kr. - Your IP is not on the whitelist and no credentials were sent.
- More than 20 failed sign-ins within a minute from your address (an IPv4 address or an IPv6 /64): every attempt gets this answer for 60 seconds, even with the right password.
What to do:
- Check your handle, the proxy user and the password in the dashboard.
- Send the username exactly as documented; keys are case-insensitive but must be known.
- Add the server's current public IP to the whitelist, or send credentials.
Slow sign-ins during a password-guessing attack. When a proxy user gets more than 10 failed sign-ins within a minute, from any addresses, the gateway slows down password checks for it, a minute at a time. An attempt from an address that has not signed in as that proxy user with its current password in the last 24 hours then waits its turn: attempts are checked one at a time and each is answered a second after its check starts, so behind a flood of guesses an attempt can reach the 10-second limit and be closed without an answer. Connections from an address on the proxy user's whitelist are never slowed, and the right password from an address that signed in with it within the last 24 hours normally is not either. If connections from a new address stall like this, connect from an address that has signed in before, or add the address to the whitelist, which always works. Once the attack stops, rotate the password if it may have leaked: the addresses an old password signed in from then count as new.
403 Forbidden
The destination is not allowed. Common causes:
- The destination is a private or reserved address (127.0.0.1, 10.0.0.0/8, 169.254.169.254 and the like), a private or undelegated name (localhost, names ending in .localhost, .local, .internal, .lan, .home, .corp, .intranet, .private, .home.arpa or .localdomain, or a name without a dot), a non-standard IPv4 spelling such as 127.1, or a mail port (25, 465, 587, 2525) or port 0.
- The hostname resolves only to such addresses. The gateway resolves every hostname itself and connects the exit to an address it checked, so a name that points inward (10.0.0.1.nip.io, or a record of your own) is refused like the address.
- The proxy user is disabled.
What to do:
- Use a public hostname or address and a port other than 0, 25, 465, 587 or 2525.
- Confirm the proxy user is enabled.
The gateway gives this answer only to a request that authenticated, with the right password or from a whitelisted address. With wrong credentials it answers 407, so a 403 never reveals that a proxy user exists.
402 Payment Required
There is no traffic left to spend on this connection. Common causes:
- The proxy user reached its monthly traffic cap.
- The account has nothing left to pay for residential traffic: its free credit, GB-pack balance and dollar credit are all used up (
balance_exhausted). Traffic draws on them in that order. - Nothing else pays for residential traffic while the account's free credit is still locked (
verification_required). A new account's free credit unlocks when the account is verified with a $1 card payment, which is added to the dollar credit, or a crypto payment of $5 or more. GB packs and dollar credit are never locked. - An
isp-ordc-connection, or a proxy user on that network, has no live subscription for it:no active subscription for this network.
What to do:
- Raise or remove the proxy user's cap in the dashboard.
- Verify the account with Verify with card under Billing in the dashboard, which unlocks the free credit. If our payment checks put that payment on hold, answer the ticket we opened about it instead.
- Buy a GB pack or add dollar credit under Billing in the dashboard.
- Start or renew the subscription for that network under Billing.
- Wait for the cap to reset: caps start over on the first day of each month (UTC).
As with 403, only a request that authenticated gets a 402; with wrong credentials the answer is a 407.
429 Too Many Requests
The account or the proxy user is over its connection limits. Common causes:
- The account already has 2,000 connections open, or opens more than 200 new ones per second (short bursts up to 400):
account rate limited. - One proxy user already has 1,000 connections open, or opens more than 100 new ones per second (bursts up to 200):
rate limited.
What to do:
- Keep fewer connections open at once; splitting work across proxy users helps only up to the account limit (2,000 open, 200 new per second).
- Retry with backoff, and reuse HTTPS (CONNECT) connections for several requests; plain
http://requests always take one connection each.
502 Bad Gateway
The gateway could not complete the request through an exit IP. Common causes:
- No IP matches the targeting you asked for (a small city combined with an ASN, for example).
- The destination refused or reset the connection from the exit IP.
- The exit did not answer within 30 seconds.
- The exit refused the gateway, or the gateway could not check your account:
proxy internal error. - The hostname does not exist, has no address, or its name servers failed to answer:
destination name did not resolve. The gateway resolves every hostname itself before it picks an exit. - Your ISP or datacenter subscription is live but no IP has been allocated yet:
no dedicated ip allocated. Billing shows the allocated IPs; this clears once one is allocated, not by retrying.
What to do:
- Widen the targeting, or check that the combination exists on this network.
- Retry. On a rotating user the next request gets a new IP; on a sticky one, use a new session ID.
- For
no dedicated ip allocated, wait for the allocation shown under Billing. - For
destination name did not resolve, check the hostname; if it is right, its name servers may be failing, and a later retry can succeed.
504 Gateway Timeout
The gateway could not resolve the hostname in time: destination name lookup timed out. It looks up every hostname itself before it picks an exit, and gives up early enough to answer within the 10 seconds a connection has to authenticate.
What to do:
- Retry after a short pause; a slow name server usually answers on a later attempt.
- If one hostname times out every time, check its DNS without a proxy.
522 Connection Timed Out
An exit IP was chosen but the destination did not answer in time. Common causes:
- The destination is slow, overloaded or silently dropping traffic from the exit IP.
- The exit reported that the destination did not answer in time. An exit that does not answer the gateway itself within 30 seconds is a 502, not a 522.
What to do:
- Retry, ideally on a different IP.
- Set a client-side timeout below the 40 seconds the gateway allows each exit it tries (10 s to reach it, 30 s for its answer) so you control the wait; after a failed first exit it may try one more.
- If one destination times out consistently, test it without a proxy to rule out the site itself.
Telling gateway errors from site errors
A response generated by the gateway carries a Proxy-Status header (RFC 9209) naming the error, and a JSON body whose error.code names it too. A response from the destination does not. Through an HTTPS (CONNECT) tunnel, many clients, curl among them, report only the status of a refused tunnel; curl -v also prints its headers, Proxy-Status included. If your code retries on status alone, check for the header first: a 403 from the gateway means the destination is blocked and will not succeed on retry, while a 403 from the site often will on a different IP.
HTTP/1.1 407 Proxy Authentication Required
Proxy-Status: scalardata; error=http_request_denied; details="unknown parameter: contry"
Proxy-Authenticate: Basic realm="scalardata"
Content-Type: application/json
Content-Length: 77
Connection: close
{"error":{"code":"unknown_parameter","message":"unknown parameter: contry"}}The details name the offending parameter only for a request that authenticated, with the right password or from a whitelisted address. A wrong password or an unknown proxy user always gets invalid credentials, whatever else the username contains.
Over SOCKS5 there are no HTTP status codes. The same conditions surface as SOCKS reply codes: an authentication failure ends the handshake, a request the gateway refuses (a blocked destination, a disabled proxy user, no traffic left, a rate limit) returns 0x02 (not allowed by ruleset), a failure inside the gateway returns 0x01 (general failure), and a failure beyond it (a hostname that does not resolve or whose lookup times out, no exit matching the targeting, an exit that cannot connect, a destination that times out) returns 0x04 (host unreachable).
Retrying
- Do not retry 407 or 403. They describe your configuration, not the network, and will repeat until something changes. The exception is a 407 from a lockout after too many failed sign-ins, which clears after 60 seconds.
- Do not retry 402 until something changes. It clears after you buy a GB pack or add dollar credit, verify the account, raise the cap, start or renew the subscription for an ISP or datacenter network, or the cap resets on the first of the month; until then every new connection gets the same answer.
- Retry 502 and 522 on a new IP. On a rotating proxy user, simply send the request again. On a sticky session, change the session ID so the retry does not land on the same exit. The exceptions are
no dedicated ip allocated, which clears when an IP is allocated, not by retrying, anddestination name did not resolve: check the hostname first, and retry later only if it is right. - Retry 504 after a short pause. The gateway could not resolve the hostname in time; a later lookup usually succeeds.
- Back off on 429. A short pause that grows with each attempt clears it without flooding the gateway with connection attempts that will also be refused.
- Keep a client timeout. Your own timeout should be the one that fires first, so the wait on a stuck request is a number you chose.
If a code keeps appearing for one destination across many IPs, send us the proxy user name, the destination and a timestamp from the contact page, and check the status page for that network's current status.