​
Error taxonomy

CodeCauseRetry?Action
400Malformed CONNECT lineNoLog the request; it’s a bug in your client
402Bandwidth quota exhausted for this periodNoUpgrade tier or wait for period reset
403Port not in allowlist (80/443/8080/8443 only); target is RFC1918 / localhost / AWS metadata; key admin-suspendedNoReview target + port; contact support if key suspended
407Auth missing / malformed / wrong secret / revoked / suspendedNoRotate if leaked; re-check credentials
429Rate limit — you’re exceeding your tier’s requests/second capYes with exponential backoffUpgrade tier if this is sustained; use sticky sessions for fewer fresh CONNECTs
502No WS-connected nodes available in the requested countryYes after 5-30sPool depth varies; beta has 1-10 nodes per country
504Gateway forwarded to a node but didn’t get tunnel_connected ACK within 15sYes, but consider targetTarget is slow, captcha-gated, or blocking

​
Response body

All error responses are plain-text, single-line bodies: 
HTTP/1.1 407 Proxy Authentication Required
Content-Type: text/plain
Content-Length: 28
Connection: close

Invalid or expired access token
We don’t return JSON error bodies on the proxy endpoint because many HTTP clients don’t surface the CONNECT response body cleanly — just the status code. Keep your retry logic focused on the status code. 
def request_with_retry(url, proxies, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            r = requests.get(url, proxies=proxies, timeout=30)
            # 502/504/429: retry with backoff
            if r.status_code in (429, 502, 504):
                time.sleep(min(60, 2 ** attempt))
                continue
            return r  # including 200 and 4xx that AREN'T rate limit
        except requests.exceptions.ProxyError:
            # Tunnel never established — transient, retry
            time.sleep(min(60, 2 ** attempt))
    raise Exception(f"Failed after {max_attempts} attempts")
Don’t retry 4xx that aren’t 429. A 407 / 402 / 403 is deterministic — retrying makes things worse and burns your rate limit.

​
Reporting incidents

If you see 502 for >1 minute, check status.atlasvpn.live first. If status is green but you’re still seeing failures, email support@atlasvpn.live with:
  1. The keyId (NOT the secret) and target host
  2. Approximate UTC timestamp
  3. Response body if any (useful for 403 — the body names the specific block reason)