> For the complete documentation index, see [llms.txt](https://docs.ipwo.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipwo.net/kai-fa-zhe-wen-dang/chang-jian-cuo-wu/api-cuo-wu-ma.md).

# API 错误码

在使用 IPWO API 或代理服务过程中，请求可能会因为认证、参数、网络或服务状态等原因返回错误。

本文整理常见 HTTP 状态码和错误类型，帮助开发者快速定位问题。

***

### 一、HTTP 状态码说明

IPWO 使用标准 HTTP 状态码表示请求结果。

| 状态码 | 类型                            | 说明     |
| --- | ----------------------------- | ------ |
| 200 | Success                       | 请求成功   |
| 400 | Bad Request                   | 请求参数错误 |
| 401 | Unauthorized                  | 身份认证失败 |
| 403 | Forbidden                     | 请求被拒绝  |
| 407 | Proxy Authentication Required | 代理认证失败 |
| 408 | Request Timeout               | 请求超时   |
| 429 | Too Many Requests             | 请求频率过高 |
| 500 | Internal Server Error         | 服务内部错误 |
| 502 | Bad Gateway                   | 网关异常   |
| 503 | Service Unavailable           | 服务暂不可用 |
| 504 | Gateway Timeout               | 网关超时   |

***

### 二、认证相关错误

#### 401 Unauthorized

#### 错误说明

认证信息无效，请求无法通过身份验证。

#### 常见原因

* 用户名错误
* 密码错误
* API Token 无效
* 账号状态异常

#### 解决方法

检查：

* 用户名是否填写正确
* 密码是否正确
* 账号是否正常使用

***

#### 407 Proxy Authentication Required

#### 错误说明

代理服务器要求身份认证，但认证信息未通过验证。

#### 常见原因

* 代理用户名错误
* 代理密码错误
* Zone 配置错误
* 使用了错误的代理格式

#### 解决方法

确认代理格式：

```
http://username:password@us.ipwo.net:7878
```

检查：

* Username
* Password
* Host
* Port

是否正确。

***

### 三、请求参数错误

#### 400 Bad Request

#### 错误说明

请求参数格式错误或缺少必要参数。

#### 常见原因

* 参数名称错误
* 参数值格式错误
* 缺少必填参数

#### 解决方法

检查：

* 请求 URL
* 参数格式
* 参数类型

参考：

《[代理参数说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/dai-li-can-shu-shuo-ming.md)》

***

### 四、权限相关错误

#### 403 Forbidden

#### 错误说明

服务器拒绝当前请求。

#### 常见原因

* 账户权限不足
* 请求目标限制访问
* 当前 IP 被目标网站限制

#### 解决方法

检查：

* 账户状态
* 代理配置
* 请求目标限制

***

### 五、请求频率错误

#### 429 Too Many Requests

#### 错误说明

请求频率超过当前限制。

#### 常见原因

* 短时间发送大量请求
* 并发数量过高
* 未设置请求间隔

#### 解决方法

建议：

* 降低请求频率
* 增加请求间隔
* 使用连接池
* 合理设置 Retry

示例：

```python
time.sleep(1)
```

***

### 六、网络连接错误

#### 408 Request Timeout

#### 错误说明

服务器等待请求响应超时。

#### 常见原因

* 网络连接不稳定
* timeout 设置过短
* 目标网站响应慢

#### 解决方法

增加请求超时时间：

```python
timeout=30
```

***

#### 502 Bad Gateway

#### 错误说明

代理节点无法正常获取目标服务器响应。

#### 常见原因

* 目标网站异常
* 网络链路问题
* 临时代理节点异常

#### 解决方法

尝试：

* 更换 Session
* 重试请求
* 更换代理地区

***

#### 504 Gateway Timeout

#### 错误说明

请求经过代理网关时等待目标响应超时。

#### 常见原因

* 目标网站响应时间过长
* 网络连接不稳定

#### 解决方法

建议：

* 增加 timeout
* 降低请求复杂度
* 添加重试机制

***

### 七、服务端错误

#### 500 Internal Server Error

#### 错误说明

服务器内部异常。

#### 解决方法

建议：

1. 稍后重新请求
2. 检查请求参数
3. 如果持续出现，请联系 IPWO 支持团队

***

#### 503 Service Unavailable

#### 错误说明

服务暂时不可用。

#### 常见原因

* 服务维护
* 临时流量增加

#### 解决方法

稍后重试。

***

### 八、代理调试流程

当请求失败时，建议按照以下顺序排查：

```
1. 检查代理地址和端口
        ↓
2. 检查用户名和密码
        ↓
3. 使用在线测试代理验证连接
        ↓
4. 检查国家地区参数
        ↓
5. 检查 Session 配置
        ↓
6. 查看错误码定位问题
```

***

### 九、错误处理建议

在生产环境中，建议：

* 对网络错误增加 Retry
* 设置合理 Timeout
* 记录错误日志
* 根据错误类型分类处理

示例：

```python
try:
    response = request()
except TimeoutError:
    retry()
except Exception:
    log_error()
```

***

### 十、相关文档

* [在线测试代理](/kai-fa-zhe-wen-dang/zai-xian-ce-shi-dai-li.md)
* [参数速查表](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/can-shu-su-cha-biao.md)
* [代理参数说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/dai-li-can-shu-shuo-ming.md)
* [认证方式说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/ren-zheng-fang-shi-shuo-ming.md)
* [Session 使用说明](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/session-shi-yong-shuo-ming.md)
* [常见错误](/kai-fa-zhe-wen-dang/chang-jian-cuo-wu.md)
* [请求最佳实践](/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/qing-qiu-zui-jia-shi-jian.md)