外观
错误处理
API 使用标准 HTTP 状态码表示请求结果。排错时先保留状态码、错误响应和请求 ID，再修改配置；不要只根据客户端弹出的简短提示判断原因。
先确认 Base URL 为 https://nexly.guangnian.xin，并且使用的是 Nexly API 控制台创建的 Key。
最小诊断流程
遇到问题时按以下顺序检查，可以快速区分 Key、模型和业务参数问题。
1. 检查服务与认证
bash
curl -i https://nexly.guangnian.xin/v1/models \
-H "Authorization: Bearer $NEXLY_API_KEY"- 返回
200：服务地址和 Key 基本正常，继续检查模型与业务请求。 - 返回
401：优先检查 Key 和请求头格式。 - 返回
403：检查 Key 权限、有效期和账号状态。 - 返回 HTML：可能请求到了登录页、反向代理或错误域名。
2. 检查模型
确认请求的 model 与 /v1/models 返回的 id 完全一致。模型列表能查询成功，但指定模型仍可能不支持当前接口。
3. 缩小请求
暂时移除工具调用、图片、结构化输出、自定义参数和长上下文，只发送一条纯文本消息。如果最小请求成功，再逐项恢复参数。
常见状态码
| 状态码 | 常见原因 | 建议处理方式 | 是否重试 |
|---|---|---|---|
400 | 参数类型错误、模型不支持参数 | 对照 API Reference，缩小请求 | 否 |
401 | Key 无效或 Bearer 格式错误 | 检查 Key、空格和环境变量 | 否 |
403 | 权限不足、Key 过期或账号受限 | 检查权限、有效期和账号状态 | 否 |
404 | 路径错误、模型或协议不存在 | 检查 /v1、模型 ID 和接口类型 | 否 |
408 | 请求超时 | 缩短输入或稍后重试 | 是 |
429 | 频率、并发或额度限制 | 查看错误消息、用量与限额 | 条件性 |
500 | 服务内部错误 | 记录请求 ID，稍后有限重试 | 是 |
502 | 上游服务异常 | 使用指数退避有限重试 | 是 |
503 | 服务暂时不可用 | 稍后重试或切换已验证模型 | 是 |
504 | 上游响应超时 | 减少生成长度或切换模型 | 是 |
错误响应
错误响应通常包含 message、type 和 code：
json
{
"error": {
"message": "Incorrect API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}排错时优先阅读 message，再结合 HTTP 状态码处理。客户端可能隐藏原始响应，可以使用 cURL 复现以查看完整内容。
常见问题定位
出现 /v1/v1
Base URL 和客户端都添加了 /v1。将客户端地址改为 https://nexly.guangnian.xin，或关闭自动拼接版本路径。
/v1/models 成功，但对话返回 404
Key 与服务正常，但模型可能不支持当前协议。检查实际请求是 /v1/chat/completions、/v1/responses 还是 /v1/messages。
非流式正常，流式失败
检查客户端或反向代理是否缓冲 SSE，确认请求设置了 stream: true。使用 cURL 时添加 -N 禁用输出缓冲。
客户端显示网络错误
用同一设备执行最小 cURL 请求。如果 cURL 成功，继续检查客户端代理、证书、Base URL 和路径拼接；如果 cURL 也失败，再检查网络、DNS 和系统时间。
重试策略
只对临时错误进行有限重试：
text
第 1 次：等待约 1 秒
第 2 次：等待约 2 秒
第 3 次：等待约 4 秒建议加入随机抖动并设置最大重试次数。400、401、403、404 等配置错误不应自动重试。流式请求中断后重新请求可能产生重复内容，业务侧需要自行处理幂等与去重。
反馈问题时提供
- 请求时间和时区。
- HTTP 状态码与完整错误响应。
- 请求接口路径和模型 ID。
- 响应头中的请求 ID（如果存在）。
- 使用的 SDK、客户端及版本。
- 是否经过公司代理、反向代理或 CC Switch 本地路由。
不要提供完整 API Key
反馈问题时请删除 Authorization 请求头，Key 最多只保留末尾 4 位用于区分。