错误说明

ISP 错误由单个 IP 返回，没有中央网关。信封与网关产品类似——HTTP 状态码 + helodata 码 + X-Helodata-Error-Code——但可能出现的代码更少，因为没有用户名语法需要解析。

ISP 错误代码

状态码	helodata 码	X-Helodata-Error-Code	含义	处理
401	20003	unknown-subuser	子账号不存在	在控制台核对
403	—	kyc-required	账号触发风险复核，KYC 待完成	见 KYC
403	—	batch-expired	批次计费周期已结束	见 IP 管理 → 续费
403	—	batch-grace-period	批次在 7 天宽限期，可用但已警示	尽快续费
403	—	ip-released	IP 已释放回池	从客户端清单中移除
403	—	restricted-category-*	目标在受限名单上	见 受限站点
403	—	account-suspended	账号被冻结	联系客服
407	20003	auth-failed	密码错误	核对，必要时轮换
407	20003	not-whitelisted	来源 IP 不在该批次白名单	在控制台添加
429	30002	concurrent-limit	该 IP 并发超限	分散到更多 IP
429	30002	rps-limit	该 IP 每秒请求超限	加 jitter，分散负载
502	40001	upstream-tls-error	目标 TLS 握手失败	见 SSL 错误
522	—	upstream-timeout	该 IP 不可达目标	在批次中另选一个 IP重试
524	—	target-timeout	目标未在时限内响应	重试或调大超时

健康感知的重试

ISP IP 稳定意味着刚返回 502/522/429 的 IP 大概率下次还会失败。总是在批次中另选 IP 重试，不要在同一 IP 上重试：

def request_with_failover(url, pool):
    for attempt in range(5):
        line = pool.next_alive()
        try:
            r = call(url, line)
            if r.status_code in (200, 301, 302, 304, 404):
                return r
            if r.status_code in (502, 522, 524, 429):
                pool.mark_bad(line)                    # 冷却该 IP
                continue
            return r                                    # 其他 4xx/5xx — 直通返回
        except Exception:
            pool.mark_bad(line)
    raise RuntimeError(f"All 5 attempts failed for {url}")

目标层错误

直通透传，同网关产品。你看不到 helodata 的 X-Helodata-Exit-IP 头——因为每个 IP 就是出口本身——但目标的响应头原样到达你。

目标的 403 或 Cloudflare 1020 通常意味着那个 IP 信誉被降权。可选：

• 标为失效并申请 替换
• 等冷却（信誉通常几小时内恢复）

helodata 问题 vs 目标问题

现象	多半原因
每个请求都 407	helodata — 认证错
某 IP 持续 522，其他正常	helodata — 该 IP 劣化，标失效
多 IP 同时 522	helodata — 该区域故障
少数 IP 被目标 403，其他正常	目标 — IP 信誉，替换
一国全部 IP 被目标 403	目标 — 国家屏蔽，换国家
同 IP 同目标反复 429	目标 — 限流，分散负载

相关

• 住宅错误说明 — 完整的直通错误语义
• 407 排错
• IP 管理 — 替换失效 IP 的流程