5xx 服务器错误

5xx 系列状态码表示服务器端出现了错误。遇到此类错误时，通常不是客户端配置问题，而是服务器端需要处理的问题。

常见 5xx 错误

状态码	名称	说明
500	Internal Server Error	服务器内部错误，通常是代码异常或配置问题
502	Bad Gateway	网关错误，上游服务无响应或返回了无效响应
503	Service Unavailable	服务不可用，通常因过载或维护中
504	Gateway Timeout	网关超时，上游服务响应超时

错误示例

{
  "error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
  }
}

原因分析

500 Internal Server Error

服务器内部代码异常
数据库连接失败
上游模型服务返回异常
配置文件错误

502 Bad Gateway

上游模型服务不可用
反向代理配置错误
网络连接中断
上游服务重启中

503 Service Unavailable

服务器过载，请求队列已满
正在维护或部署新版本
上游模型服务限流或熔断

504 Gateway Timeout

上游模型服务响应时间过长
网关超时设置过短
网络延迟过高

排查步骤

1. 确认是否为偶发错误

# 重复发送请求，观察是否持续报错
for i in $(seq 1 5); do
  echo "Request $i:"
  curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" \
    "$BASE_URL/v1/chat/completions" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5}'
  sleep 2
done

2. 检查请求参数

确认请求参数没有异常值：

max_tokens 是否设置过大
请求体 JSON 是否格式正确
模型名称是否正确

3. 检查服务状态

访问管理后台，查看是否有维护公告
查看零派智能API 的状态页面
尝试调用 /v1/models 接口，确认服务是否在线

4. 查看详细错误信息

# 获取完整的响应体
curl -v "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}' 2>&1

解决方案

客户端重试策略

对于偶发的 5xx 错误，实现自动重试：

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=30)

            if response.status_code >= 500:
                wait = 2 ** attempt
                print(f"Server error {response.status_code}. Retrying in {wait}s...")
                time.sleep(wait)
                continue

            return response

        except requests.exceptions.RequestException as e:
            wait = 2 ** attempt
            print(f"Request failed: {e}. Retrying in {wait}s...")
            time.sleep(wait)

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

降低请求复杂度

减小 max_tokens 参数
简化 prompt 内容
使用更快的模型（如 gpt-4o-mini 替代 gpt-4o）

检查并降低并发

临时降低应用的并发请求量
添加请求间隔
使用队列平滑请求流量

何时联系管理员

遇到以下情况时，建议联系管理员：

持续出现 500 错误：服务器内部可能有未处理的异常
频繁出现 502/503 错误：上游服务可能存在稳定性问题
特定模型持续报错：该模型的上游服务可能已下线
错误信息中包含异常详情：将完整错误信息提供给管理员以便排查
大量用户同时受到影响：可能是全局性的服务故障

联系时提供以下信息

完整的错误响应（状态码和响应体）
请求的时间点
使用的 API Key（可脱敏）
请求的模型名称
请求的 Base URL
是否能稳定复现