跳转到内容
零派智能文档 零派智能文档
返回主站

网络错误

网络错误是指客户端在连接服务器过程中遇到的问题，通常与网络配置、代理设置或 DNS 解析有关。

常见网络错误

错误码错误名称说明
ECONNREFUSED连接被拒绝目标地址和端口没有服务监听，或被防火墙拒绝
ETIMEDOUT连接超时在规定时间内无法建立连接
ENOTFOUND域名解析失败无法解析域名对应的 IP 地址
ECONNRESET连接被重置连接被对端或网络设备强制关闭
EPIPE管道破裂写入已关闭的连接
EHOSTUNREACH主机不可达网络路由无法到达目标主机

原因分析

ECONNREFUSED

  • Base URL 中的端口错误（如使用了 HTTP 端口而非 HTTPS 端口）
  • 服务未启动或已崩溃
  • 防火墙规则拒绝了连接

ETIMEDOUT

  • 网络延迟过高
  • 目标服务器不可达
  • 本地网络问题（如 WiFi 信号差）

ENOTFOUND

  • 域名拼写错误
  • DNS 服务器配置问题
  • 域名尚未解析生效

ECONNRESET

  • 网络不稳定导致连接中断
  • 服务器或中间代理主动断开连接
  • 请求体过大被拦截

排查步骤

1. 检查 URL 是否正确

Terminal window
# 打印完整的 Base URL，检查拼写
echo "$BASE_URL"


# 确认协议、域名和端口是否正确
# 正确格式：https://api.example.com/v1

2. 检查网络连通性

Terminal window
# Ping 测试
ping api.example.com


# 端口连通性测试
nc -zv api.example.com 443


# 或使用 telnet
telnet api.example.com 443

3. 检查 DNS 解析

Terminal window
# 使用 nslookup 检查域名解析
nslookup api.example.com


# 使用 dig 检查 DNS 记录
dig api.example.com


# 尝试使用公共 DNS 解析
dig @8.8.8.8 api.example.com

4. 检查代理设置

Terminal window
# 查看当前代理环境变量
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY
echo $NO_PROXY

5. 使用 cURL 详细模式调试

Terminal window
curl -v "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY" 2>&1

查看详细的连接过程，包括 DNS 解析、TCP 握手、TLS 协商等步骤。

解决方案

代理配置问题

如果你需要通过代理访问 API，确保正确配置代理：

Terminal window
# 设置 HTTP/HTTPS 代理
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
# Python requests 使用代理
import requests


proxies = {
    "http": "http://proxy.example.com:8080",
    "https": "http://proxy.example.com:8080",
}


response = requests.post(
    url,
    headers=headers,
    json=data,
    proxies=proxies,
    timeout=60
)
// JavaScript (Node.js) 使用代理
const { HttpsProxyAgent } = require("https-proxy-agent");


const agent = new HttpsProxyAgent("http://proxy.example.com:8080");


fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
    agent: agent,
});

如果你不需要代理但系统设置了代理，清除代理设置：

Terminal window
# 清除代理
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

DNS 解析问题

Terminal window
# 临时使用公共 DNS
# 修改 /etc/resolv.conf 添加：
# nameserver 8.8.8.8
# nameserver 1.1.1.1

或者在代码中直接指定 IP 地址（不推荐，仅用于调试）：

Terminal window
curl --resolve api.example.com:443:<IP地址> "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

SSL/TLS 证书问题

Terminal window
# 临时跳过 SSL 验证（仅用于调试，不要在生产环境使用）
curl -k "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"
# Python：临时跳过 SSL 验证
import requests
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)


response = requests.get(url, headers=headers, verify=False)

防火墙和网络限制

  1. 确认你的网络环境是否允许访问 API 的端口（通常为 443）
  2. 如果在公司内网，检查是否需要配置 VPN 或白名单
  3. 检查本地防火墙规则是否拦截了出站请求

实现重试机制

对于偶发的网络错误，实现自动重试：

import time
import requests


def request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data, timeout=60)
            return response
        except (requests.ConnectionError, requests.Timeout) as e:
            wait = 2 ** attempt
            print(f"Network error: {e}. Retrying in {wait}s...")
            time.sleep(wait)


    raise Exception(f"Max retries ({max_retries}) exceeded")