Errors and troubleshooting

Identify the proxy protocol and the stage that failed. HTTP proxy setup can return an HTTP status, JSON error code, and Proxy-Status header. SOCKS5 setup returns handshake statuses and binary reply codes. A destination response received after successful tunnel setup belongs to the destination.

HTTP proxy error reference

Status	Error code	Meaning	First action
400	invalid_request	Malformed proxy request or invalid hostname/port	Correct the request format
400	ip_target_unsupported	The destination is an IP address	Use a destination hostname
501	method_not_supported	The HTTP proxy request is neither CONNECT nor absolute-form forwarding	Use the HTTP client’s proxy settings
407	invalid_credentials	Proxy credentials or routing username are invalid	Check the username and complete key secret
407	key_expired	The key has expired	Create a replacement key
407	key_revoked	The key has been revoked	Use a valid replacement key
407	account_disabled	The workspace is disabled	Check its status in the console and contact support
502	no_exit_available	No eligible exit matches the requested route	Check filters and location availability
503	routing_unavailable	Route selection could not complete	Retry a safe request later with bounded backoff
502	exit_unreachable	The selected exit could not be reached	Check session policy; retry a safe request with backoff
504	exit_timeout	The selected exit did not respond in time	Reduce immediate retries and check destination access
502	target_dns_failed	The exit could not resolve the hostname to permitted addresses	Check the hostname and destination policy
502	target_unreachable	The exit could not connect to the destination	Check the destination hostname, port, and availability
502	target_closed	An HTTP forward destination closed without a response	Retry only if the request can safely be repeated

Admission limits can also close a connection before setup without a structured HTTP response. A connection can close before parsing or when its initial request misses the setup deadline.

HTTP error shape

Structured setup failures use this shape:

HTTP/1.1 502 Bad Gateway
Proxy-Status: ports.io; error=destination_unavailable; details="target_unreachable"
Content-Type: application/json

{"error":{"code":"target_unreachable","message":"the exit could not connect to the target"}}

Use error.code for machine classification. The Proxy-Status header’s details field carries the same code, which can help when an HTTP library exposes a failed CONNECT response’s headers but not its body. Do not depend on error.message as a stable programmatic identifier. A 407 also includes Proxy-Authenticate: Basic.

SOCKS5 failures

SOCKS5 does not return HTTP 407 or a JSON error body during setup. First determine whether method negotiation, username/password authentication, or the CONNECT request failed.

Stage	Value	Meaning	First action
Method negotiation	0xff	No acceptable authentication method	Enable SOCKS5 username/password authentication
Username/password authentication	0x01	Authentication failed	Check routing username, full key, expiration, revocation, and workspace status

After successful authentication, these CONNECT reply codes can occur:

Reply code	Meaning in this gateway	First action
0x01	General failure, including an invalid request, unavailable routing, or an unreachable exit	Check request format and route; retry transient failures with backoff
0x02	Destination IP address rejected by policy	Enable remote DNS and use a destination hostname
0x04	Destination DNS or connection failure	Check hostname, port, reachability, and destination restrictions
0x06	Selected exit timed out	Retry a safe request later with backoff
0x07	Command not supported	Use CONNECT; BIND and UDP ASSOCIATE are unsupported
0x08	Unknown address type	Use a SOCKS5 client that sends a domain-name address

SOCKS replies group several internal failure causes. Authentication failure does not distinguish an invalid key from an expired or revoked one. Record the client error and the stage instead of expecting the HTTP error catalog’s JSON codes.

For curl or Python Requests, use socks5h:// to send the destination hostname. Their socks5:// mode resolves locally and sends an IP address, which receives 0x02. A destination URL containing an IP literal also fails with remote DNS enabled. See Protocols and limits.

Resolve authentication failures

1. Use a valid routing username such as v1_rotate; account IDs and key display names do not belong in it.
2. Send the complete proxy key secret as the password. Remove copied whitespace and newlines.
3. Configure proxy Basic authentication for HTTP, or username/password authentication for SOCKS5. Do not use destination authentication or a bearer token.
4. Check whether the key has expired or been revoked, whether its workspace is enabled, and whether it belongs to the assigned environment.

If an unchanged key fails across valid usernames, investigate the workspace and service status before creating more keys. Repeatedly creating keys will not resolve a service outage.

Check destination and session failures

For no_exit_available, look for filters that contradict each other or remove every permitted country. A recognized country code can still have no active exit.

For destination DNS or connection failures, check that the hostname and port are correct and reachable from a public network. Private and special-purpose destinations are blocked by default. A destination may also refuse connections or deny requests based on its own policy.

For a session, preserve the strategy and filter policy associated with the ID. Choose a new ID when changing either. Fixed sessions do not fail over an unreachable bound exit. See Sessions and rotation.

Handle admission failures and connection drops

Reduce parallel connections and avoid a burst of immediate retries. Proxy setup can be rejected by source-IP, concurrency, or connection-rate limits, unavailable routing, or destination policy.

After HTTP 200 Connection Established or a successful SOCKS5 CONNECT reply, the tunnel can still close because of a network failure, an origin or client disconnect, or the idle/lifetime deadline. Established traffic is not replayed by the proxy. Retry only when your application can safely repeat the operation; use capped exponential backoff and jitter for transient failures.

Reproduce with a minimal client

Use your assigned endpoint, an existing valid key, a plain routing username, and a destination hostname:

curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 15 \
  --max-time 30 \
  https://example.com/

For SOCKS5, set PORTS_PROXY_URL to the assigned socks5h:// endpoint with its port. For HTTP proxying, use the assigned http:// or https:// endpoint. A standard socks5h:// connection cannot be sent directly to a TLS-only proxy port.

Keep verbose traces private: they can include proxy or destination credentials. Remove credentials before sharing any diagnostic output.

Information to include in a support report

• Timestamp and timezone.
• Proxy protocol, endpoint, and client/library version.
• Routing username, destination hostname and port, and concurrency level.
• Failure stage: negotiation, authentication, tunnel setup, or destination response.
• HTTP proxy status/error code, or SOCKS handshake status/reply code when available.
• Key ID or visible suffix, without the full secret.
• Whether a minimal request reproduces the problem and whether other destinations work.

The customer-facing error response currently has no documented request-ID field. Record your own request correlation ID when troubleshooting application batches.