Skip to main content
The network returns standard HTTP status codes plus a few custom codes for proxy-specific conditions. Each response includes a short plaintext body explaining what happened.

​
Authentication & request errors

​
400 Bad Request
standard
Your HTTP request is malformed. Check your proxy client is sending a valid HTTP CONNECT or request line.
​
407 Proxy Authentication Required
standard
Username or password is wrong, or your targeting modifiers contain an unrecognised value. Double-check credentials in the dashboard.Body: Incorrect username or password
​
417 Expectation Failed
standard
Your client sent an Expect: header the proxy can’t satisfy. Remove it or switch libraries.

​
Plan limit errors

​
452 Bandwidth Exceeded
custom
You’ve used all the bandwidth on your plan. Top up or upgrade from the dashboard.Body: exceeded bandwidth limit
​
453 Thread Limit Exceeded
custom
You’re making more concurrent connections than your plan allows. Reduce concurrency or upgrade.Body: exceeded threads limit

​
Targeting errors

These only apply to the residential network — datacenter and ISP don’t accept targeting modifiers.
​
454 Invalid Country Code
custom
The country-<code> modifier isn’t a recognised country. Use lowercase ISO 3166-1 alpha-2 codes (e.g. us, de, jp).Body: invalid country code
​
454 Invalid State Code
custom
The state-<code> value isn’t recognised for the country you picked. Use the standard regional subdivision code.Body: invalid state code
​
454 Invalid City Code
custom
The city-<code> value isn’t recognised, or no IPs are available for that city. Try city-ran to let the network pick a city within your targeted state.Body: invalid city code
​
455 Invalid TTL
custom
The ttl-<minutes> value is outside the allowed range. TTL must be a positive integer within the supported lifetime range.Body: invalid ttl

​
Upstream & network errors

​
502 Bad Gateway
standard
The target site couldn’t be reached. Could be DNS failure, target-side refusal, or a transient network issue. Retry with backoff.
​
500 Internal Server Error
standard
An unexpected error occurred on our side. If you see this repeatedly, contact support with a timestamp and the full response.
​
503 Service Unavailable
standard
A transient internal error. Retry with backoff — if it persists, contact support.

​
Handling errors in code

Most proxy libraries surface these as either a connection error (for 4xx on the proxy itself) or as the HTTP status of the response (for upstream errors). Check both. 
import requests

proxy = "http://USER-country-zz:PASSWORD@pr-us.proxies.fo:13337"  # invalid country
proxies = {"http": proxy, "https": proxy}

try:
    r = requests.get("https://api.ipify.org", proxies=proxies, timeout=30)
    if r.status_code == 454:
        print("Targeting error:", r.text.strip())
    elif r.status_code == 452:
        print("Out of bandwidth — top up your plan")
    elif r.status_code == 453:
        print("Too many concurrent connections")
    elif r.status_code >= 500:
        print(f"Upstream issue ({r.status_code}) — retry with backoff")
    else:
        print(r.text)
except requests.exceptions.ProxyError as e:
    # 407 typically surfaces as a ProxyError
    print("Auth failed — check credentials:", e)

​
Summary table

CodeMeaningAction
400Bad requestFix client request format
407Auth failedCheck username / password
417Expectation failedRemove Expect: header
452Bandwidth exhaustedTop up plan
453Thread limit hitLower concurrency or upgrade
454Invalid country / state / cityFix targeting modifier
455Invalid TTLUse a valid ttl-<minutes> value
500Internal errorContact support
502Upstream unreachableRetry with backoff
503Service unavailableRetry; contact support if persistent
If something doesn’t match what you see, reach out on Telegram with a request timestamp and we’ll investigate.