错误码对照

HTTP 转发和 HTTPS CONNECT 建立隧道前的错误，都返回明确的状态码、X-NextProxy-Error 响应头和安全的 JSON 正文。先看状态码分类，再用机器码定位；错误信息不包含内部地址或代理密码。

HTTP 状态与机器码

出口连接过程中收到的 403 / 407 统一返回 502 upstream_connection_failed，不表示客户凭据错误。认证服务调用超时属于 503 service_unavailable。

407 同时返回 Proxy-Authenticate: Basic realm="NextProxy"。缺失凭据与错误凭据都使用 407，用机器码区分，不再统一返回 403。

HTTP/1.1 407 Proxy Authentication Required
Proxy-Authenticate: Basic realm="NextProxy"
X-NextProxy-Error: invalid_credentials
Content-Type: application/json; charset=utf-8
Content-Length: 92
Cache-Control: no-store
Connection: close

{"error":{"code":"invalid_credentials","message":"Proxy username or password is incorrect"}}

正文的 message 是面向客户的说明，不作为程序判断依据；请匹配 code。某些 HTTP 客户端在 CONNECT 失败时不暴露正文，此时读取响应头。网关错误均带 Content-Length 与 Cache-Control: no-store；429、503 还带 Retry-After: 1，至少等待 1 秒后再有限退避重试。此处是代理响应的等待值，与 REST 提取接口的等待值分别判断。

用 cURL 查看错误

curl -v --connect-timeout 10 --max-time 30 \
  --proxy 'http://GATEWAY_HOST:58971' \
  --proxy-user 'USERNAME-country-US:PASSWORD' \
  'https://api.ipify.org'

普通 HTTP 转发可用 curl -i 查看状态行、响应头和 JSON。curl -v 的调试输出写到标准错误；不要只使用隐藏错误的 -s，需要安静输出时用 -sS。分享日志前删除 Proxy-Authorization 和真实密码。不要把 Markdown 的 [文字](链接) 当成代理 URL，也不要从截图识别凭据。

网关错误与目标网站错误

200 Connection Established 只表示 CONNECT 隧道建立成功。之后目标网站返回的 403、429 或其他状态属于目标网站，与代理认证失败不同。HTTPS 隧道建立后网关不会解密目标 HTTP 响应，也不能再插入 JSON 错误；后续中断通过连接关闭和运营记录定位。

重试前先辨别响应来自哪里。网关 400、402、403、407 需要先修正参数、额度或权限；429 要降并发；502、503、504 可有限指数退避。对非幂等目标请求，先确认是否已执行，不能盲目重放。

没有 HTTP 响应的边界

协议识别前的全局连接保护、来源 IP 并发/速率保护、首字节超时和资源高水位仍可能直接关闭 TCP 连接。成功建立隧道后的断流也不会变成新的 HTTP 状态。此时记录发生时间、入口、账号和客户端错误，交由运营查询，不把所有断连都解释成 403。

SOCKS5

SOCKS5 使用协议协商和 REP，不发送 HTTP 状态、JSON 或 X-NextProxy-Error。

认证阶段协议只能报告成功或失败，不能把所有 HTTP 分类一一编码。定位时可临时用同一组凭据发 HTTP CONNECT 请求读取机器码，再回到 SOCKS5；运营端保留更具体的失败原因。

提取接口错误码

响应是结构化的 JSON（type=json 时），有具体的 code：

完整参数说明见 提取接口。

客户 API 错误码

统一结构：

{
  "error": {
    "code": "machine_readable_code",
    "message": "给人看的说明",
    "fields": { "FieldName": "validationTag" }
  }
}

常见的：

代理端口使用本文的 HTTP/SOCKS5 契约；客户管理 API 与提取 API 的 401、403 是各自的 REST 鉴权规则，不能替换成代理 407。系统排查见 排错流程。