Proxy error reference
Proxy errors are data-plane failures from HTTP or SOCKS5 ingress. They are separate from the JSON errors returned by the account 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, 12, and 13 can carry a more specific wire message than the default below.
| 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 balance The wire message may be custom. | 500 | Not a network retry | Check or add account balance in the dashboard. |
| 14 | ErrorRemoteProxy |
Remote proxy connection error | 500 or 503 | Bounded backoff | Retry may select a different remote proxy. |
| 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. |
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. Litport deliberately replaces the upstream provider's status, headers, and body with the generic 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.
| Reply | Meaning | Possible categories |
|---|---|---|
0x01 |
General failure | Internal, upstream selection, PPG upstream, remote connection, or upstream I/O failure. Commonly codes 2, 7, 14, 15, or 16. |
0x02 |
Connection not allowed | Authentication, token, hub/protocol, PPG, concurrent-connection, and rate-limit failures share this reply. |
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#
- Correct credentials, hub, protocol, geography, balance, or client concurrency before retrying deterministic failures.
- Retry transient internal, selection, and upstream failures with bounded exponential backoff and jitter.
- Retry an interrupted or upstream application operation only when repeating that operation is safe.
- 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.