文档菜单

入门

代理基础

代理API

响应缓存

Litport API

MCP服务器

代理错误参考

代理错误是HTTP或SOCKS5入口产生的数据平面故障。它们与Litport API返回的JSON错误是分开的。

HTTP代理错误#

对于HTTP入口，请先检查以下响应头，再解读HTTP状态码：

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

数字响应头是主要判断依据。仅凭HTTP状态码并不足够：若干兼容路径使用500，而部分网络故障会被推断为503。错误码11和12实际返回的消息可能比下表中的默认消息更具体。

错误码13（账户余额不足）是500惯例的例外：它返回402 Payment Required。HTTPS隧道建立失败时，许多客户端只报告状态行，因此客户端仅凭状态码就能得知问题出在余额上。请先充值，再重试。

错误码 符号 默认消息或返回消息 HTTP状态码 重试建议 处理方法
0 ErrorNone 空 无错误响应 不适用 将请求视为成功。
1 ErrorPanic panic 500 不要在紧密循环中重试 退避后重试一次，然后联系客服并附上请求的相关记录。
2 ErrorInternal Internal proxy error 500或503 有限退避 重试有限次数，然后联系客服。
3 ErrorInterrupted Connection was interrupted 500 仅当应用操作可安全重复时 重试前检查客户端和目标的超时。
4 ErrorNoToken Token not found 407 更正凭证后 检查代理用户名、密码、主机和端口。
5 ErrorNoAccess Access denied 为兼容性返回500 不要自动重试 检查令牌状态、账户权限和目标地址策略。
6 ErrorLimited You have reached the limit of concurrent connections 403 有可用容量后 关闭空闲连接或降低并发。
7 ErrorNoProxy Internal proxy error 500 有限退避 短暂重试；若始终没有可用上游，联系客服。
8 ErrorHubMismatch Proxy host mismatch, check token settings 500 更正节点后 使用控制台中为该令牌显示的节点。
9 ErrorHubProxyTypeMismatch Proxy type mismatch, check token settings 500 更正入口后 使用该令牌当前的HTTP或SOCKS5端点。
10 ErrorRateLimited Too many requests 403 需要退避 降低该入口模式下新请求或新连接的速率。
11 ErrorPpgGetProxy PPG proxy error 可能被具体的返回消息替代。 500 取决于自定义消息 更正代理池、地理或会话参数；否则退避后重试。
12 ErrorPpgStats PPG stats error 返回消息可能是自定义的。 500 有限退避 短暂重试，错误持续则联系客服。
13 ErrorPpgNotEnoughUnits Insufficient account balance 402 网络重试无法解决 在控制台查看账户余额或充值。
14 ErrorRemoteProxy Remote proxy connection error 500或503 有限退避 退避后重试；重试可能会选择另一个远程代理。如果按国家、州/省或城市定位且持续出现，该位置当前可能没有在线的IP：稍后重试，或扩大位置范围。
15 ErrorUpstreamConnection Upstream server connection error 500或503 取决于对目标重试是否安全 重试前检查目标地址和重试策略。
16 ErrorPpgUpstreamResponse Internal proxy error 500 有限退避 短暂重试；若持续出现，联系客服并提供节点、令牌ID、目标地址、时间戳和错误码16，切勿提供代理密码。
17 ErrorPackageBandwidthExceeded packageBandwidthExceeded 403 网络重试无法解决 只有设有流量上限的旧套餐才会出现此错误：它已用完当期流量。等待下一周期开始，或联系客服。
18 ErrorPackageEntitlementUnavailable packageEntitlementUnavailable 503 有限退避 未能及时读取或预留套餐权益。短暂重试；若持续出现，联系客服并提供节点、令牌ID和时间戳。
19 ErrorPackageInactive packageInactive 403 不要自动重试 套餐已暂停或已取消。在控制台检查其状态和支付方式。
20 ErrorPackageExpired packageExpired 403 不要自动重试 套餐周期已结束。在控制台续费或购买新套餐。
21 ErrorPackageMissing packageMissing 403 不要自动重试 该令牌指向的套餐已不存在。联系客服并提供令牌ID。
22 ErrorPackageStale packageEntitlementStale 403 不要自动重试 节点保存的套餐记录过旧，不可信。联系客服并提供节点、令牌ID和时间戳。
23 ErrorClientAborted Client closed the connection 未发送（客户端已关闭） 不适用 客户端在请求完成前关闭或重置了连接。检查客户端超时和连接复用。

对于“多地点”共享设备令牌，错误码7加消息noHealthyRoute表示已保存的目标当前没有运行正常的设备。请读取该令牌的位置，然后等待恢复或选择其他可用目标。城市始终保持不变：在该城市没有可用手机的运营商，会回退到同一城市的另一家运营商，effective显示实际使用的运营商。

对https:// HTTP代理端点的TLS握手失败，表现为在发送任何HTTP响应之前连接就被关闭，因此没有可检查的X-Proxy-Error-Code。如果https://连接立即关闭，请检查URL协议、主机名（不是IP地址），以及客户端是否已为代理连接信任Litport缓存根证书。

PPG上游故障#

错误码16表示按流量计费的上游无法处理该请求。它并不表示目标站点返回了Litport的500。错误码14表示远程代理拒绝或中断了连接，例如目标位置没有在线的IP。在这两种情况下，Litport都会有意用自己固定的错误替换上游提供商的状态码、响应头和响应体。

HTTP客户端应根据X-Proxy-Error-Code: 16进行分支处理，而不是只看HTTP状态码。SOCKS5客户端收到的是通用失败，不带数字响应头；要查看Litport错误码，可通过该令牌的HTTP入口重现请求，但只能重现安全且幂等的请求。

请使用有上限的退避策略重试。如果错误持续存在，请联系客服，并提供节点、令牌ID、目标地址、时间戳和错误码16，切勿提供代理密码。准入之后交换的流量，包括通用错误响应，仍受现行使用政策约束。

SOCKS5应答#

SOCKS5不提供X-Proxy-Error-Code或X-Proxy-Error-Message。多个内部类别被有意合并为同一个应答。

大多数令牌和账户检查，包括余额不足，都在用户名/密码登录阶段进行，早于客户端发送请求。该阶段的失败会以登录被拒的形式关闭连接，即使密码正确，大多数客户端也会将其报告为认证失败。

应答 含义 可能的类别
auth 0x01 登录被拒绝 用户名/密码步骤（RFC 1929）失败，连接在任何请求之前关闭。大多数令牌和账户检查在这一步执行：令牌未知、已禁用或已过期，或密码错误（4），令牌访问权限不匹配（5），节点错误（8）或协议错误（9），PPG代理池参数无效（11），PPG计量（12），余额不足（13），以及套餐状态（17–22）。客户端通常将其报告为认证失败。
0x01 一般性故障 内部故障，或请求被受理后上游连接失败。常见错误码为2、14、15或16。
0x02 不允许连接 登录后请求被拒绝：目标地址或网络规则（5）、并发连接数限制（6）、无可用上游（7）、速率限制（10）、PPG上游选择（11），或所选上游不支持的PPG UDP。
0x07 不支持该命令 未实现所请求的SOCKS5命令；这不是X-Proxy-Error-Code。

要区分具体原因，请对相应的HTTP入口重现同一个安全且幂等的请求（使用相同的凭证），然后检查其响应头。如果重现会重复产生副作用，或存在其他不安全因素，则不要重现。

安全重试策略#

  1. 对于确定性失败，先纠正凭证、节点、协议、地理位置、余额或客户端并发，再重试。
  2. 对于暂时性的内部故障、选择故障和上游故障，使用有上限的指数退避并加入随机抖动后重试。
  3. 仅当重复执行某个操作是安全的，才重试被中断的操作或上游应用操作。
  4. 切勿运行没有间隔的紧密重试循环。保留有限次重试序列中第一次和最后一次的证据。

提交给客服的信息#

请提供Litport节点、HTTP或SOCKS5入口、UTC时间戳、令牌ID、目标主机和端口，以及观察到的错误码/消息或SOCKS5应答。相关时请一并提供请求方法。

MarkdownOpenAPI