# 错误说明

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

## ISP 错误代码

| 状态码   | `X-Helodata-Error-Code` | 含义                | 处理                                                                                                      |
| ----- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `401` | `unknown-subuser`       | 子账号不存在            | 在控制台核对                                                                                                  |
| `403` | `kyc-required`          | 账号未完成 KYC         | 见 [KYC](/helodata-zh/zhang-hu-yu-ji-fei/kyc.md)                                                         |
| `403` | `batch-expired`         | 批次计费周期已结束         | 见 [IP 管理 → 续费](https://docs.helodata.com/helodata-zh/chan-pin/overview-2/pages/cFgkUq9quVGUMTS4XWgf#续费) |
| `403` | `batch-grace-period`    | 批次在 7 天宽限期，可用但已警示 | 尽快续费                                                                                                    |
| `403` | `ip-released`           | IP 已释放回池          | 从客户端清单中移除                                                                                               |
| `403` | `restricted-category-*` | 目标在受限名单上          | 见 [受限站点](/helodata-zh/chan-pin/overview/restricted-targets.md)                                          |
| `403` | `account-suspended`     | 账号被冻结             | 联系客服                                                                                                    |
| `407` | `auth-failed`           | 密码错误              | 核对，必要时轮换                                                                                                |
| `407` | `not-whitelisted`       | 来源 IP 不在该批次白名单    | 在控制台添加                                                                                                  |
| `429` | `concurrent-limit`      | 该 IP 并发超限         | 分散到更多 IP                                                                                                |
| `429` | `rps-limit`             | 该 IP 每秒请求超限       | 加 jitter，分散负载                                                                                           |
| `502` | `upstream-tls-error`    | 目标 TLS 握手失败       | 见 [SSL 错误](/helodata-zh/gu-zhang-pai-cha/ssl-errors.md)                                                 |
| `522` | `upstream-timeout`      | 该 IP 不可达目标        | 在批次中**另选一个 IP**重试                                                                                       |
| `524` | `target-timeout`        | 目标未在时限内响应         | 重试或调大超时                                                                                                 |

## 健康感知的重试

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

```python
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** 信誉被降权。可选：

* 标为失效并申请 [替换](https://docs.helodata.com/helodata-zh/chan-pin/overview-2/pages/cFgkUq9quVGUMTS4XWgf#替换失效-ip)
* 等冷却（信誉通常几小时内恢复）

## helodata 问题 vs 目标问题

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

## 相关

* [住宅错误说明](/helodata-zh/chan-pin/overview/error-definitions.md) — 完整的直通错误语义
* [407 排错](/helodata-zh/gu-zhang-pai-cha/407.md)
* [IP 管理](/helodata-zh/chan-pin/overview-2/ip-management.md) — 替换失效 IP 的流程


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/chan-pin/overview-2/error-definitions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.