常见错误与处理

先保存请求时间、模型 ID、HTTP 状态和 X-Oneapi-Request-Id；再按错误信息定位。状态码只是线索，同一个码可能对应不同原因。

连不上、404 或返回网页

1. 确认使用 https://api.avanovo.com/v1 作为本文 SDK 的 Base URL。
2. 检查最终请求是否为 /v1/responses 或 /v1/chat/completions，避免重复 /v1。
3. 检查网络、代理和客户端是否实际采用新配置。
4. 返回 HTML 登录页通常意味着请求走错路径；不要继续按 JSON 解析。

填写规则见接入地址。不要通过关闭 TLS 证书校验解决连接问题。

HTTP 401：认证失败

检查是否使用本站 API Key、变量是否已传给当前进程、值是否带有多余空格，以及 Key 是否到期、停用或删除。不要把网站密码或其他平台 Key 当作本站调用凭据。

更改环境变量后，已经启动的客户端可能需要重启才能读取新值。

HTTP 403 或模型不可用

确认 Key 分组、模型限制和账号权限，再用 GET /v1/models 查看当前可见范围。列表可见仍需确认协议；公开模型广场存在的型号不保证你的 Key 能使用。

若使用 IP 限制，检查代理或网络变化后的实际出口。不要靠反复换任意型号掩盖权限问题。

余额不足，或有余额仍无法调用

分别查看钱包余额与 Key 剩余额度，并检查有效期、模型权限以及预扣需求。Codex 的长上下文可能需要比简单文本请求更高的预扣额度。

“无限配额”不绕过账户余额。当前没有自助在线充值路径；余额为零时先完成配置准备，有额度后再调用。详见余额与费用。

HTTP 429：先区分发生位置

发生位置	检查与处理
模型 API 请求	查看返回错误，可能是用户频率限制、站点额度限制或上游限流；降低并发，若返回 Retry-After 则遵循它，设置有上限的退避
网站登录、退出、刷新	网页认证接口可能按 IP 限流；停止反复刷新和登录，等待后再试，不需要因此更换 API Key

不要用无限重试或同时打开多个标签页测试恢复。模型请求重试可能产生新的费用。

HTTP 5xx、超时或流式输出中断

保留请求 ID、时间和脱敏错误，先核对使用日志。收到部分文本不代表请求结束；Responses 流需检查完成或失败事件。

连接断开不能证明上游没有执行，也不能证明费用为零。不要自动把失败请求当作免费请求重放。

HTTP 200，但没有完整回答

Responses 检查 status、incomplete_details 与输出项类型；Chat 检查 finish_reason。可能是输出预算不足，也可能返回工具调用而非最终文本。

SDK 的 output_text 是文本便利属性，不能代替对工具项与状态的检查。增加预算前，先确认费用边界。

配置成功但本站没有日志

确认已经实际发送任务，而非仅保存配置；检查 provider、Base URL、Key 和日志时间范围。Codex 另需确认本次进程的独立配置目录。具体步骤见 Codex。

需要进一步核对时保留的信息

保存时间及其时区、客户端与版本、模型 ID、请求 ID、状态码、脱敏错误和复现步骤。不要分享完整 Key、Authorization 头、账号密码或敏感业务正文。尚未确定的信息应标为未知，不凭状态码推断供应商故障或退款结论。