代理错误码
网关各状态码的含义、常见原因和处理办法。
网关自身无法处理请求时,会返回以下状态码之一,并附上说明原因的 JSON 正文 {"error":{"code":"…","message":"…"}},格式与 REST API 的错误相同。其他响应,包括目标网站返回的 403 或 429,都来自目标站点,网关原样透传。网关无法读取的请求,或 10 秒内未完成认证的请求,会被直接关闭、不作应答;已建立的隧道在流量耗尽或其代理用户被停用、删除时,也只会被直接关闭。
407 Proxy Authentication Required
网关无法将连接匹配到任何代理用户。常见原因:
- 密码错误,或密码已轮换。
- 用户名中的
handle-name部分与账号下的任何代理用户都不匹配。 - 定向参数拼写错误,或取值不在网关服务范围内,例如
kr以外的国家代码。 - 来源 IP 不在白名单中,且未发送凭据。
- 同一地址(IPv4 地址或 IPv6 /64)1 分钟内认证失败超过 20 次:此后 60 秒内即使密码正确也会收到此响应。
处理方式:
- 在控制台核对账号标识、代理用户名称和密码。
- 严格按文档格式发送用户名;键不区分大小写,但必须是已定义的键。
- 把服务器当前公网 IP 加入白名单,或改为发送凭据。
遭遇密码猜测攻击时认证变慢。 某个代理用户在 1 分钟内认证失败超过 10 次(无论来自哪些地址)时,网关会放慢对该代理用户的密码校验,每次持续 1 分钟。在此期间,过去 24 小时内未曾用该代理用户当前密码认证成功的地址发起的尝试需要排队:尝试逐个校验,每次在校验开始 1 秒后才得到应答,因此排在大量猜测请求之后的尝试可能等到 10 秒时限,被直接关闭而不作应答。来自该代理用户白名单内地址的连接不会被放慢;过去 24 小时内用当前密码认证成功过的地址再次发送该密码时,通常也不会被放慢。如果来自新地址的连接因此卡住,请改用以前认证成功过的地址连接,或把该地址加入白名单,白名单在任何情况下都有效。如果密码可能已泄露,请在攻击停止后轮换密码:此后,用旧密码认证过的地址也都会被视为新地址。
403 Forbidden
网关拒绝了该请求。常见原因:
- 目标是私有或保留地址(如 127.0.0.1、10.0.0.0/8、169.254.169.254),私有或未委派的域名(localhost,以 .localhost、.local、.internal、.lan、.home、.corp、.intranet、.private、.home.arpa、.localdomain 结尾的域名,或不含点的名称),127.1 这类非标准 IPv4 写法,或邮件端口(25、465、587、2525)及 0 端口。
- 主机名只解析到这类地址。网关会自行解析每个主机名,并让出口连接经它检查过的地址,因此指向内部地址的域名(如 10.0.0.1.nip.io,或你自己添加的 DNS 记录)会与该地址一样被拒绝。
- 代理用户已停用。
处理方式:
- 使用公网可访问的主机名或地址,并避开 0、25、465、587、2525 端口。
- 确认代理用户处于启用状态。
只有通过认证的请求(密码正确,或来自白名单地址)才会收到此响应。凭据错误时返回 407,因此 403 不会暴露某个代理用户是否存在。
402 Payment Required
当前连接已没有可用流量。常见原因:
- 代理用户已达到每月流量上限。
- 账号可用于住宅流量的余额已全部用完(
balance_exhausted):赠送额度、流量包余量和充值余额都为 0。流量按这一顺序扣除。 - 账号的赠送额度尚未解锁,且没有其他可用于住宅流量的余额(
verification_required)。新账号验证后赠送额度才会解锁:用银行卡支付 $1(这 $1 会存入充值余额),或用加密货币支付 $5 或以上。流量包和充值余额不会被锁定。 isp-、dc-连接或该网络的代理用户没有生效中的订阅:no active subscription for this network。
处理方式:
- 在控制台提高或取消该代理用户的上限。
- 在控制台的账单页面点击银行卡验证验证账户,赠送额度随即解锁。如果该笔付款未通过支付风险检查而被暂缓,请改为回复我们为此创建的工单。
- 在控制台的账单页面购买流量包或充值。
- 在账单页面开通或续订该网络的订阅。
- 等待上限重置:代理用户上限按自然月统计,每月 1 日(UTC)清零。
与 403 相同,只有通过认证的请求才会收到 402;凭据错误时返回 407。
429 Too Many Requests
账号或代理用户超出了连接数限制。常见原因:
- 账号已有 2,000 个并发连接,或每秒新建连接超过 200 个(瞬时最多 400 个):
account rate limited。 - 单个代理用户已有 1,000 个并发连接,或每秒新建连接超过 100 个(瞬时最多 200 个):
rate limited。
处理方式:
- 减少同时打开的连接数;把任务分摊到多个代理用户,最多只能用到账号上限(并发 2,000 个、每秒新建 200 个)。
- 采用退避策略重试,并让 HTTPS(CONNECT)连接承载多个请求;普通
http://请求始终是每个请求一个连接。
502 Bad Gateway
网关无法通过出口 IP 完成请求。常见原因:
- 没有 IP 满足所要求的定向条件(例如小城市叠加 ASN)。
- 目标拒绝或重置了来自出口 IP 的连接。
- 出口未在 30 秒内响应。
- 出口拒绝了网关的连接,或网关无法校验你的账号:
proxy internal error。 - 主机名不存在、没有对应的地址,或其域名服务器未能应答:
destination name did not resolve。网关在选择出口之前,会先自行解析每个主机名。 - ISP 或数据中心订阅已生效,但尚未分配 IP:
no dedicated ip allocated。已分配的 IP 可在账单页面查看;需等分配完成才能恢复,重试无效。
处理方式:
- 放宽定向条件,或确认该组合在当前网络上确实存在。
- 直接重试。轮换模式下,下一个请求会分配新 IP;粘性会话请更换会话 ID。
- 遇到
no dedicated ip allocated时,请等待账单页面显示 IP 分配完成。 - 遇到
destination name did not resolve时,请检查主机名;若主机名无误,可能是其域名服务器出现故障,稍后重试可能成功。
504 Gateway Timeout
网关未能及时解析主机名:destination name lookup timed out。网关在选择出口之前会自行解析每个主机名,并会及早放弃,确保能在连接完成认证的 10 秒时限内作出应答。
处理方式:
- 稍等片刻后重试;域名服务器响应慢时,之后的尝试通常就能得到应答。
- 若某个主机名每次都超时,绕过代理直接检查它的 DNS。
522 Connection Timed Out
已分配出口 IP,但目标未在规定时间内响应。常见原因:
- 目标响应缓慢、过载,或静默丢弃来自出口 IP 的流量。
- 出口报告目标未在规定时间内响应。出口本身未在 30 秒内响应网关时,返回的是 502 而非 522。
处理方式:
- 重试,最好换一个 IP。
- 将客户端超时设得比网关等待每个出口的 40 秒(连接出口 10 秒、等待其应答 30 秒)更短,由自己掌控等待时长;第一个出口失败后,网关可能再试一个。
- 若某个目标持续超时,绕过代理直接测试,排除站点自身的问题。
区分网关错误与站点错误
网关生成的响应带有 Proxy-Status 头(RFC 9209),其中注明错误类型,并附 JSON 正文,其 error.code 同样注明错误;目标站点的响应则没有这个头。通过 HTTPS(CONNECT)隧道时,包括 curl 在内的许多客户端在隧道被拒绝时只显示状态码;用 curl -v 运行可以看到包括 Proxy-Status 在内的响应头。如果代码只根据状态码决定是否重试,请先检查该头:网关返回的 403 说明请求被网关拒绝,重试不会成功;站点返回的 403 换个 IP 往往就能通过。
HTTP/1.1 407 Proxy Authentication Required
Proxy-Status: scalardata; error=http_request_denied; details="unknown parameter: contry"
Proxy-Authenticate: Basic realm="scalardata"
Content-Type: application/json
Content-Length: 77
Connection: close
{"error":{"code":"unknown_parameter","message":"unknown parameter: contry"}}只有通过认证的请求(密码正确,或来自白名单地址),details 才会写出有问题的参数。密码错误或代理用户不存在时,不论用户名还有什么其他问题,一律返回 invalid credentials。
SOCKS5 没有 HTTP 状态码,同样的情况以 SOCKS 应答码体现:认证失败直接终止握手;被网关拒绝的请求(目标被禁止、代理用户已停用、流量用尽、连接数超限)返回 0x02(规则不允许);网关内部错误返回 0x01(一般性失败);网关之外的失败(主机名无法解析或解析超时、没有符合定向条件的出口、出口连接失败、目标超时)返回 0x04(主机不可达)。
重试策略
- 407 和 403 不要重试。它们反映的是配置问题而非网络问题,配置不变,结果不会变。唯一的例外是认证失败过多被锁定时的 407,60 秒后即可恢复。
- 402 在情况改变前不要重试。只有购买流量包或充值、验证账户、提高上限、开通或续订 ISP、数据中心网络的订阅,或等到每月 1 日上限重置后才会恢复,在此之前每个新连接都会收到同样的结果。
- 502 和 522 换 IP 重试。轮换模式下直接重发请求即可;粘性会话请更换会话 ID,避免重试落到同一出口。
no dedicated ip allocated和destination name did not resolve例外:前者需等 IP 分配完成,重试无效;后者请先检查主机名,只有主机名无误时才稍后重试。 - 504 稍等片刻后重试。网关未能及时解析主机名;稍后再次解析通常会成功。
- 429 采用退避。逐步拉长每次重试前的等待时间即可恢复,不要用注定会被拒绝的连接持续冲击网关。
- 保留客户端超时。客户端自己的超时应最先触发,这样卡住的请求最多等多久,就由客户端自己掌控。
如果同一目标在多个 IP 上反复出现同一状态码,请通过联系页面把代理用户名称、目标地址和时间戳发给我们,并到服务状态页面查看该网络的当前状态。