一、超时（Timeout）问题
1. 常见原因
- 网络延迟或中转站节点不稳定
- 请求的模型响应慢（如长文本生成、复杂推理）
- 高峰期服务器负载过高，请求排队
- 客户端设置的超时时间过短
2. 排查步骤
- 查看中转站的服务状态页，确认是否有节点故障
- 测试简单请求（如"ping"）是否正常，排除Key和账户问题
- 尝试切换接入地址（主用/备用）
- 增加客户端超时时间（建议设置60秒以上）
- 使用流式（stream）模式，避免长时间等待完整响应
3. 解决方案
- 使用流式请求：
stream: true，边生成边接收 - 缩短生成参数：降低
max_tokens，使用更短的prompt - 切换备用节点地址
- 选择更稳定的中转站
二、401 未授权错误
1. 常见原因
- API Key错误或已过期
- API Key的权限不足，无法调用请求的模型
- 账户余额不足，平台返回401
- 请求地址不正确，使用了错误的base_url
2. 排查步骤
- 登录中转站控制台，确认API Key是否正确复制（注意前后空格）
- 检查账户余额是否充足
- 确认请求的模型是否在你的Key权限范围内
- 核对base_url是否为中转站提供的接入地址
3. 解决方案
- 重新生成API Key并更新代码
- 充值或切换到有余额的账户
- 检查模型名称拼写是否正确
- 使用curl测试基础连通性：
curl https://your-relay.com/v1/models -H "Authorization: Bearer YOUR_KEY"
三、429 速率限制错误
1. 常见原因
- 短时间内请求过于频繁，触发平台限流
- 并发数超过账户限制
- 触发了特定模型的速率限制
2. 排查步骤
- 查看返回的Retry-After头，了解需要等待多久
- 检查代码中是否有循环请求未加间隔
- 确认账户的并发限制
3. 解决方案
- 实现指数退避重试（exponential backoff）
- 添加请求间隔，避免突发流量
- 降低并发数，使用请求队列
- 升级账户套餐获取更高限额
四、其他常见错误
400 Bad Request
通常是请求体格式错误，检查：模型名称是否正确、messages格式是否符合规范、参数类型是否正确。
404 Not Found
请求路径错误，确认base_url是否正确，路径是否包含/v1前缀。
500 Internal Server Error
中转服务器内部错误，可能是上游模型服务故障。等待几分钟后重试，或查看状态页。
502/503 Service Unavailable
上游模型服务不可用或中转站节点过载。切换备用地址或稍后重试。
五、通用排查流程
- 先看状态页，排除平台故障
- 用curl做最小化测试，排除代码问题
- 检查Key、余额、模型权限
- 切换节点地址
- 联系客服，提供请求日志
更多技术问题可参考我们的API中转站排行榜，各平台的接入文档和常见问题汇总可供查阅。