Documentation menu

Start

Proxy fundamentals

Proxy APIs

Response cache

Litport API

MCP server

Proxy error reference

Proxy errors are data-plane failures from HTTP or SOCKS5 ingress. They are separate from the JSON errors returned by the Litport API.

HTTP proxy errors#

For HTTP ingress, inspect these response headers before interpreting the HTTP status:

X-Proxy-Error-Code: 10
X-Proxy-Error-Message: Too many requests

The numeric header is the primary discriminator. HTTP status alone is insufficient: several compatibility paths use 500, while some network failures are inferred as 503. Codes 11 and 12 can carry a more specific wire message than the default below.

Code 13 (insufficient account balance) is the exception to the 500 convention: it returns 402 Payment Required. Many clients report only the status line when an HTTPS tunnel fails, so the status alone tells them the balance is the problem. Add balance before retrying.

Code Symbol Default or wire message HTTP status(es) Retry guidance What to do
0 ErrorNone Empty No error response Not applicable Treat the request as successful.
1 ErrorPanic panic 500 No tight-loop retry Retry once with backoff, then contact support with request evidence.
2 ErrorInternal Internal proxy error 500 or 503 Bounded backoff Retry a limited number of times, then contact support.
3 ErrorInterrupted Connection was interrupted 500 Only when the application operation is safe Check client and target timeouts before retrying.
4 ErrorNoToken Token not found 407 After correcting credentials Check the proxy username, password, host, and port.
5 ErrorNoAccess Access denied 500 for compatibility No automatic retry Check token status, account access, and destination policy.
6 ErrorLimited You have reached the limit of concurrent connections 403 After capacity is available Close idle connections or reduce concurrency.
7 ErrorNoProxy Internal proxy error 500 Bounded backoff Retry briefly; contact support if no upstream becomes available.
8 ErrorHubMismatch Proxy host mismatch, check token settings 500 After correcting the hub Use the hub shown for the token in the dashboard.
9 ErrorHubProxyTypeMismatch Proxy type mismatch, check token settings 500 After correcting the ingress Use the token's current HTTP or SOCKS5 endpoint.
10 ErrorRateLimited Too many requests 403 Backoff required Reduce new-request or new-connection rate for the ingress mode.
11 ErrorPpgGetProxy PPG proxy error May be replaced by a specific wire message. 500 Depends on the custom message Correct pool, geography, or session parameters; otherwise retry with backoff.
12 ErrorPpgStats PPG stats error The wire message may be custom. 500 Bounded backoff Retry briefly, then contact support if the error continues.
13 ErrorPpgNotEnoughUnits Insufficient account balance 402 Not a network retry Check or add account balance in the dashboard.
14 ErrorRemoteProxy Remote proxy connection error 500 or 503 Bounded backoff Retry with backoff; a retry may select a different remote proxy. If you target a country, region or city and this persists, that location may have no IP online right now: retry later or widen the location.
15 ErrorUpstreamConnection Upstream server connection error 500 or 503 Depends on destination safety Check the destination and retry policy before retrying.
16 ErrorPpgUpstreamResponse Internal proxy error 500 Bounded backoff Retry briefly; if it persists, contact support with the hub, token ID, destination, timestamp, and code 16—never the proxy password.
17 ErrorPackageBandwidthExceeded packageBandwidthExceeded 403 Not a network retry Only an older package with a traffic cap can hit this: it has used its traffic for the current period. Wait for the period to renew, or contact support.
18 ErrorPackageEntitlementUnavailable packageEntitlementUnavailable 503 Bounded backoff The package's entitlement could not be read or reserved in time. Retry briefly; if it persists, contact support with the hub, token ID, and timestamp.
19 ErrorPackageInactive packageInactive 403 No automatic retry The package is suspended or cancelled. Check its status and payment method in the dashboard.
20 ErrorPackageExpired packageExpired 403 No automatic retry The package period has ended. Renew it, or buy a new package, in the dashboard.
21 ErrorPackageMissing packageMissing 403 No automatic retry The token names a package that no longer exists. Contact support with the token ID.
22 ErrorPackageStale packageEntitlementStale 403 No automatic retry The hub is holding a package record too old to trust. Contact support with the hub, token ID, and timestamp.
23 ErrorClientAborted Client closed the connection Not sent (the client had already closed) Not applicable Your client closed or reset the connection before the request finished. Check client timeouts and connection reuse.

For a Multi-location Shared Mobile token, code 7 with message noHealthyRoute means the saved target currently has no healthy device. Read the token's location, then wait for recovery or choose another available target. The city is always kept: a carrier with no working phone in that city falls back to another carrier in the same city, and effective shows the carrier actually in use.

A failed TLS handshake against the https:// HTTP proxy endpoint surfaces as a closed connection before any HTTP response is sent, so there is no X-Proxy-Error-Code to inspect. If a https:// connection closes immediately, check the URL scheme, the hostname (not an IP address), and that the client trusts the Litport cache root for the proxy connection.

PPG upstream failures#

Code 16 means a pay-per-GB upstream could not serve the request. It does not mean the destination returned Litport's 500. Code 14 means the remote proxy refused or dropped the connection, for example because no IP is online in the targeted location. In both cases Litport deliberately replaces the upstream provider's status, headers, and body with its own fixed error.

HTTP clients should branch on X-Proxy-Error-Code: 16, not the HTTP status alone. SOCKS5 clients receive general failure without the numeric header; only reproduce a safe, idempotent request through the token's HTTP ingress to inspect the Litport code.

Retry with bounded backoff. If the error persists, contact support with the hub, token ID, destination, timestamp, and code 16—never the proxy password. Traffic exchanged after admission, including the generic error response, remains subject to the existing usage policy.

SOCKS5 replies#

SOCKS5 does not expose X-Proxy-Error-Code or X-Proxy-Error-Message. Multiple internal categories intentionally collapse into one reply.

Most token and account checks, including insufficient balance, run during the username/password login, before the client sends a request. A failure there closes the connection as a rejected login, which most clients report as an authentication failure even when the password is correct.

Reply Meaning Possible categories
auth 0x01 Login rejected The username/password step (RFC 1929) failed and the connection closed before any request. Most token and account checks run here: unknown, disabled or expired token or a wrong password (4), token access mismatch (5), wrong hub (8) or protocol (9), invalid PPG pool parameters (11), PPG accounting (12), insufficient balance (13), and package state (17–22). Clients usually report this as an authentication failure.
0x01 General failure Internal failure, or the upstream connection failed after the request was admitted. Commonly codes 2, 14, 15, or 16.
0x02 Connection not allowed The request was refused after login: destination or network rules (5), concurrent-connection limit (6), no available upstream (7), rate limit (10), PPG upstream selection (11), or PPG UDP that the selected upstream does not support.
0x07 Command not supported The requested SOCKS5 command is not implemented; this is not an X-Proxy-Error-Code.

To disambiguate, reproduce the same safe, idempotent request and credentials against the corresponding HTTP ingress, then inspect its headers. If reproduction would repeat a side effect or is otherwise unsafe, do not reproduce it.

Safe retry policy#

  1. Correct credentials, hub, protocol, geography, balance, or client concurrency before retrying deterministic failures.
  2. Retry transient internal, selection, and upstream failures with bounded exponential backoff and jitter.
  3. Retry an interrupted or upstream application operation only when repeating that operation is safe.
  4. Never run a tight retry loop. Preserve the first and last evidence from a bounded sequence.

Support evidence#

Include the Litport hub, HTTP or SOCKS5 ingress, UTC timestamp, token ID, destination host and port, and observed error code/message or SOCKS5 reply. Include the request method when relevant.

MarkdownOpenAPI