Q401：返回 401 Unauthorized / Incorrect API key 如何排查？
- 字符检查：检查复制的 API Key 前后是否包含多余空格、换行符或引号；
- 变量验证：确认当前终端环境变量已正确加载该 Key；
- 端点匹配：确认请求 Base URL 格式正确（OpenAI 兼容端点为
/v1，Anthropic 兼容端点为/anthropic），避免因路径错误导致鉴权失败。
Q402：返回 403 Forbidden 是什么原因？
- IP 白名单拦截：检查该 Key 是否绑定了 IP 白名单，且当前发起调用的公网出口 IP 不在允许列表中；
- 管理接口权限限制：创建 Key、修改预算、查询全局余额等管理接口仅允许默认 API Key 调用，使用普通业务 Key 调用将返回 403；
- 账户模型权限限制：确认当前账号或子 Key 是否具备该模型的调用权限。
Q403：出现 413 Request Entity Too Large 怎么处理？
单次请求 Payload 体积超出网关限制。常见于对话历史超长、或将多张高分辨率图片转为 Base64 编码直接嵌入请求体中。
Q404：返回 429 Too Many Requests 如何排查？
- 核对错误详情：速率超限通常返回 429，账户余额不足通常返回 402。请先查看响应正文明确原因；
- 定位限制维度：确认是触发了 Key 的日/月费用上限、账号并发保护（同时在途请求数），还是瞬时请求频次（RPS/RPM/TPM）超限；
- 实施退避重试：客户端代码中实现指数退避重试（Exponential Backoff），并设置最大重试次数与超时限制。
Q406：所有请求均报 ConnectionRefused 或 ProxyError？
- 排查代理配置：检查终端是否残留已失效的代理环境变量（如 VPN 客户端退出后残留的
HTTP_PROXY/HTTPS_PROXY）； - 测试网络连通性：通过
nslookup检查域名解析，测试到目标服务器 443 端口的 TCP/TLS 连通性； - 网络环境对照：切换至移动热点或备用网络进行对照，排除企业内网网关或本地防火墙拦截。
Q407：校园网或企业统一出口偶发连接超时，可能是什么原因？
部分校园网与企业内网统一出口存在 NAT 端口耗尽、跨境链路拥堵或安全网关对长连接的主动重置行为。排查建议：- 使用手机热点做网络对照测试；
- 将请求 Base URL 切换为国内加速入口
https://api.nonelinear.com.cn/v1进行连通性比对。
Q408：为什么开启 thinking 或调整推理等级后报错？
不同大模型对思考参数的字段定义有所不同（如 budget_tokens、reasoning_effort）。若当前客户端版本未兼容目标模型的思考参数，建议在客户端中关闭 thinking 模式，或使用官方推荐的标准参数调用。
Q410：长对话进行到一半开始反复报错，怎样恢复？
长对话中累积的未闭环工具调用或庞大历史极易引发异常。推荐将前期对话提炼为简洁的阶段性任务摘要，然后在客户端中开启全新 Session 继续执行，避免将已损坏的超长历史重复带入后续请求。Q411：向技术支持团队提交排查工单时，需要提供哪些关键信息？
为确保快速准确定位，请一次性提供以下已脱敏信息：- 故障发生时间与时区；
- 使用的客户端与版本（如 Codex CLI、Claude Code、Python SDK）；
- 请求的完整 Model ID 与接口路径；
- 请求 ID：响应体中的
id或 调用明细 中的请求 ID（若连接未建立请注明“无请求 ID”）； - API Key 脱敏标识；
- HTTP 状态码与脱敏后的完整报错文本。