# 错误码总览

请求失败时，**三个信号**告诉你问题在哪。按以下顺序读：

1. **HTTP 状态码** — 粗类别（认证、限流、上游、目标）
2. **`X-Helodata-Error-Code`** 响应头 — 精确原因（仅网关原产的错误带）
3. **`X-Helodata-Request-Id`** — 寻求客服支持时附上

一行粘贴的日志胜过千次猜测。

## 速查

| 状态码                 | 最可能原因           | 首查页面                                                                                                                 |
| ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `400`               | 用户名语法错          | [用户名格式](/helodata-zh/kuai-su-ru-men/username-format.md)                                                              |
| `401` / `407`       | 凭证错 / IP 未加入白名单 | [407 代理身份验证失败](/helodata-zh/gu-zhang-pai-cha/407.md)                                                                 |
| `403`               | 受限目标或未通过 KYC    | `X-Helodata-Error-Code` 与 [受限站点](/helodata-zh/chan-pin/overview/restricted-targets.md)                               |
| `429`               | 触发限流            | [限流](/helodata-zh/api-can-kao/rate-limits.md)                                                                        |
| `502`               | IP 池耗尽、TLS 问题   | [SSL / TLS 错误](/helodata-zh/gu-zhang-pai-cha/ssl-errors.md)、放宽用户名筛选                                                  |
| `522`               | 上游超时            | [522 连接超时](/helodata-zh/gu-zhang-pai-cha/522.md)                                                                     |
| `524`               | 目标响应慢           | 目标慢，重试或调大客户端超时                                                                                                       |
| Cloudflare `1020` 页 | 被识破地理或指纹        | [验证码](/helodata-zh/gu-zhang-pai-cha/captchas.md)、[IP 地理位置不匹配](/helodata-zh/gu-zhang-pai-cha/ip-location-mismatch.md) |

## 如何读一个失败请求

真实示例：

```
HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: not-whitelisted
X-Helodata-Request-Id: req_01HX2K3PQ4M5
Content-Type: application/json

{"code":"not-whitelisted","message":"Source IP 203.0.113.5 isn't on the whitelist for sub-user sub_01HX..."}
```

要抓取三件事：

* **状态 407** → 认证类
* **`not-whitelisted`** → 来源 IP 不在该子账号白名单
* **`req_01HX2K3PQ4M5`** → 保存好，找客服时我们可凭它定位这次调用

## 常见现象

| 你看到的             | 多半原因                  | 跳转                                                                  |
| ---------------- | --------------------- | ------------------------------------------------------------------- |
| 首请求总返回 407       | 用户名语法或密码错             | [407](/helodata-zh/gu-zhang-pai-cha/407.md)                         |
| 在城市级筛选下随机 `522`  | IP 池过小                | [522](/helodata-zh/gu-zhang-pai-cha/522.md)                         |
| 部分站点 OK，部分 SSL 错 | 目标 TLS 配置异常或 CA 证书库过期 | [SSL/TLS 错误](/helodata-zh/gu-zhang-pai-cha/ssl-errors.md)           |
| 某国家大量验证码         | 指纹不匹配或池烧毁             | [验证码](/helodata-zh/gu-zhang-pai-cha/captchas.md)                    |
| `Exit-IP` 地理判错   | MaxMind 库延迟           | [IP 地理位置不匹配](/helodata-zh/gu-zhang-pai-cha/ip-location-mismatch.md) |
| 响应时间 5–10 秒      | 移动 / 反爬延迟             | [速度过慢](/helodata-zh/gu-zhang-pai-cha/slow-speeds.md)                |
| 页面就是不渲染          | JS 重的站点或被屏蔽           | [网站打不开](/helodata-zh/gu-zhang-pai-cha/website-wont-load.md)         |

## 错误信号读不懂时

记录 `状态码 + X-Helodata-Error-Code + X-Helodata-Request-Id` 三元组并发邮件至 <support@helodata.com>。`Request-Id` 在调用后 7 天内可用于检索完整请求记录。

## 各产品错误码表

完整代码表在各产品参考页：

* [住宅错误说明](/helodata-zh/chan-pin/overview/error-definitions.md)
* [移动错误说明](/helodata-zh/chan-pin/overview-1/error-definitions.md)
* [ISP 错误说明](/helodata-zh/chan-pin/overview-2/error-definitions.md)


---

# 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/gu-zhang-pai-cha/troubleshooting.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.