常见问题与错误排查
最快排查顺序
按下面的顺序检查，每次只改变一个变量：
- Base URL：确认使用 OpenAI
/v1、Gemini/v1beta或 Claude 无版本后缀地址。 - API Key：确认客户端实际加载的是当前有效 Key，且没有多余空格或引号。
- 模型 ID：从控制台重新复制完整 ID，并确认它支持所选协议。
- 最小 curl：使用快速开始中的请求排除客户端配置问题。
- 控制台记录：核对请求时间、模型、状态码、用量和 request ID（如有）。
- 脱敏诊断：保留必要字段，移除完整 Key 和敏感请求内容后再提交问题。
401：认证失败
401 通常表示服务端没有接受当前认证信息。
- 检查请求是否发送
Authorization: Bearer $THQ_API_KEY。 - 确认环境变量已加载到启动客户端的同一个终端或进程。
- 重新复制 Key，排除前后空格、换行和旧配置覆盖。
- 在控制台确认 Key 未被撤销、停用或替换。
不要把完整 Key 粘贴到聊天、工单、日志或截图中。
403：请求被拒绝
403 表示认证可能已被识别，但当前请求没有通过权限或策略检查。
- 确认账户状态及控制台要求确认的条款。
- 检查目标模型是否对当前账户可用。
- 检查 API Key、模型、协议和使用场景是否匹配。
- 使用最小请求排除插件附加参数或组织级代理规则的影响。
具体权限和限制以控制台当前显示为准。
404：端点或模型不匹配
先检查是否混用了三类地址后缀：
404 也可能来自请求路径拼写错误、客户端自动追加了重复路径，或所选模型不支持当前端点。记录客户端最终请求地址，并用控制台中的模型 ID 重新验证。
429：额度、速率或并发受限
429 表示当前请求触及了额度、速率、并发或其他动态限制。
- 在控制台核对可用额度和当前限制。
- 降低并发，避免多个客户端同时使用同一个 Key 运行批量任务。
- 减少无限或过于激进的自动重试；对临时限流使用逐步增加的等待时间。
- 如果响应包含建议等待时间，客户端应遵循该值。
模型价格、额度和限制以控制台当前显示为准。
5xx：网关或上游服务异常
5xx 可能是临时服务端或上游错误，也可能由特定模型、输入或高并发触发。
- 保存请求时间、模型 ID、HTTP 状态码和 request ID（如有）。
- 使用最小、非敏感输入重试一次，确认问题是否稳定复现。
- 检查控制台使用记录，判断请求是否到达并产生记录。
- 稍后使用有上限的退避策略重试，不要持续高频发送相同请求。
客户端保存配置后仍不生效
- 完全退出并重新启动客户端；已运行的进程不会自动读取新环境变量。
- 检查项目配置、用户配置、环境变量和启动参数之间的覆盖顺序。
- 确认修改的是当前客户端实际读取的配置文件和配置档案。
- 查看客户端日志或网络请求，核对最终 Base URL 与模型 ID，而不是只看设置页面。
- 删除重复的版本或路径后缀，再执行最小请求。
可以把 API Key 写进前端吗
不要在浏览器前端、移动端安装包或可公开下载的静态文件中直连长期有效的 API Key。构建产物、源码映射、浏览器网络面板和扩展都可能暴露其中的密钥。
面向终端用户的产品应由可信服务端保管 Key，并在服务端实施身份校验、额度控制、参数校验和日志脱敏。发现泄露后立即在控制台撤销旧 Key，再更新受影响的服务。
仍未解决
通过控制台当前可见的支持或问题反馈入口提交脱敏信息。请附上请求时间及时区、客户端及版本、完整模型 ID、HTTP 状态码、request ID（如有）、脱敏错误和已经执行的排查步骤。
不要发送完整 API Key，也不要发送包含敏感业务数据的完整请求正文。