Error reference

HTTP forwarding and HTTPS CONNECT errors before tunnel establishment return a specific status, an X-NextProxy-Error header and a safe JSON body. Use the status for the category and the machine code for the cause. Responses do not expose internal addresses or proxy passwords.

HTTP status and machine codes

An exit connection that receives 403 or 407 during establishment returns 502 upstream_connection_failed; it is not a customer credential error. Authentication-service timeouts return 503 service_unavailable.

407 also returns Proxy-Authenticate: Basic realm="NextProxy". Both missing and incorrect credentials use 407, distinguished by the machine code; incorrect credentials no longer produce a generic 403.

HTTP/1.1 407 Proxy Authentication Required
Proxy-Authenticate: Basic realm="NextProxy"
X-NextProxy-Error: invalid_credentials
Content-Type: application/json; charset=utf-8
Content-Length: 92
Cache-Control: no-store
Connection: close

{"error":{"code":"invalid_credentials","message":"Proxy username or password is incorrect"}}

The body's message is a customer-facing explanation, not a programmatic contract: match code. Some clients hide the body when CONNECT fails; read the response header in that case. All gateway errors include Content-Length and Cache-Control: no-store; 429 and 503 also include Retry-After: 1. Wait at least that long before a bounded retry. The header concerns this proxy response, not the separate retry values of REST extraction APIs.

Inspecting errors with cURL

curl -v --connect-timeout 10 --max-time 30 \
  --proxy 'http://GATEWAY_HOST:58971' \
  --proxy-user 'USERNAME-country-US:PASSWORD' \
  'https://api.ipify.org'

For plain HTTP forwarding, use curl -i to see the status, headers and JSON. curl -v writes diagnostics to standard error. Avoid hiding failures with -s; use -sS when quiet output is needed. Remove Proxy-Authorization and real passwords before sharing logs. Do not paste Markdown [text](URL) as a proxy URL or obtain credentials through screenshot recognition.

Gateway errors versus destination errors

200 Connection Established means only that the CONNECT tunnel is ready. A later 403, 429 or other HTTP status belongs to the destination website, not proxy authentication. Once an HTTPS tunnel is established, the gateway does not decrypt the destination response and cannot insert a JSON error. Later interruptions are diagnosed using the closed connection and operator records.

Identify the response source before retrying. Gateway 400, 402, 403 and 407 require fixing parameters, quota or permissions; 429 requires lowering concurrency; 502, 503 and 504 allow bounded exponential backoff. For non-idempotent destination requests, verify whether the action executed before replaying it.

Cases without an HTTP response

Before protocol detection, global connection protection, per-source-IP concurrency/rate limits, first-byte timeouts and resource high-water marks may still close TCP directly. A stream interrupted after tunnel establishment also cannot become a new HTTP status. Record the time, gateway, account and client error for support instead of interpreting every disconnect as 403.

SOCKS5

SOCKS5 uses negotiation and REP values, not HTTP statuses, JSON or X-NextProxy-Error.

The authentication protocol can only report success or failure, so HTTP categories do not map one-to-one. For diagnosis, temporarily send an HTTP CONNECT request with the same credentials to obtain the machine code, then return to SOCKS5. Operator records retain more specific failure causes.

Extract API error codes

Responses are structured JSON (with type=json) carrying a specific code:

Full parameter documentation is in Extract API.

Client API error codes

A uniform structure:

{
  "error": {
    "code": "machine_readable_code",
    "message": "human-readable explanation",
    "fields": { "FieldName": "validationTag" }
  }
}

The common ones:

Proxy ports use the HTTP/SOCKS5 contract above. Customer management and extraction API 401/403 responses follow their own REST authentication rules and must not be replaced with proxy 407. See the troubleshooting flow.