# 错误说明

网关同时返回标准 HTTP 状态码与 `X-Helodata-Error-Code` 头，后者精确指明原因。重试前请**同时**根据状态码与该头判断。

## 网关层错误（helodata 产生）

| 状态码   | `X-Helodata-Error-Code` | 含义                                                                    | 处理                                                         |
| ----- | ----------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
| `400` | `bad-username`          | 用户名不符合语法                                                              | 复核 [用户名格式](/helodata-zh/kuai-su-ru-men/username-format.md) |
| `400` | `unknown-region`        | 国家代码不识别                                                               | 使用 ISO-3166 alpha-2                                        |
| `400` | `state-without-region`  | 有 `state` 但缺 `region`                                                 | 补充 `region`                                                |
| `400` | `city-without-state`    | 有 `city` 但缺 `state`                                                   | 补充 `state`                                                 |
| `400` | `session-incomplete`    | `session` 与 `sesstime` 未成对出现                                          | 二者必须同时存在                                                   |
| `400` | `sesstime-out-of-range` | TTL 超 30（住宅）                                                          | 减小 `sesstime`                                              |
| `401` | `unknown-subuser`       | 子账号不存在                                                                | 在控制台核对                                                     |
| `403` | `restricted-category-*` | 目标被屏蔽，详见 [受限站点](/helodata-zh/chan-pin/overview/restricted-targets.md) | 申请例外                                                       |
| `403` | `account-suspended`     | 账号因计费或滥用被冻结                                                           | 联系客服                                                       |
| `407` | `auth-failed`           | 密码错误                                                                  | 核对，必要时轮换                                                   |
| `407` | `not-whitelisted`       | 来源 IP 不在白名单                                                           | 在控制台添加                                                     |
| `429` | `concurrent-limit`      | 并发连接超限                                                                | 限流或升级套餐                                                    |
| `429` | `rps-limit`             | 每秒请求超限                                                                | 带 jitter 退避重试                                              |
| `502` | `pool-empty`            | 池中无匹配 IP                                                              | 放宽地理/ASN 筛选                                                |
| `502` | `upstream-tls-error`    | 目标 TLS 握手失败                                                           | 详见 [SSL 错误](/helodata-zh/gu-zhang-pai-cha/ssl-errors.md)   |
| `522` | `upstream-timeout`      | 后端 IP 不可达                                                             | 重试，多为瞬时                                                    |
| `522` | `insufficient-pool`     | 组合筛选后在线 IP 不足 10                                                      | 放宽筛选                                                       |
| `524` | `target-timeout`        | 目标站点超时未响应                                                             | 重试或加大客户端超时                                                 |

## 目标层错误（直通）

目标站点返回的错误由 helodata 原样透传。出现以下响应头即说明代理成功，问题在下游：

```
X-Helodata-Exit-IP: 198.51.100.42
X-Helodata-Exit-Geo: us/ca/la
X-Helodata-Exit-ASN: 7922
```

如果带着这些头同时收到目标的 `403`，那是**目标本身**拒绝了该 IP，不是 helodata。

## 常见直通状态码

| 状态码                 | 常见原因       | 缓解             |
| ------------------- | ---------- | -------------- |
| 目标返回 `403`          | 反爬系统拒绝该 IP | 轮换 IP、补请求头、降速  |
| 目标返回 `429`          | 被目标限流      | 单 IP 降速、增加轮换   |
| 目标返回 `503`          | 目标过载       | 退避重试           |
| Cloudflare `1020` 页 | 地理或指纹被识破   | 加请求头、用粘性会话、换国家 |

## 重试策略

按下表区分对待，不同错误应对方式不同：

```python
RETRYABLE_GATEWAY = {429, 502, 522, 524}

def should_retry(status, err_code):
    if status in (400, 401, 403, 407):
        return False                          # 配置问题，重试无意义
    if status in RETRYABLE_GATEWAY:
        return True
    return False
```

`rps-limit` 类 429，带 1–5 秒 jitter；`pool-empty` 只有在放宽筛选后才重试。

## 日志建议

每次请求都记录 `status`、`X-Helodata-Error-Code`、`X-Helodata-Exit-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/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.