AI API 错误排查指南
使用 KunAI AI API 错误排查指南，根据 401、403、404、429、502 等状态码检查鉴权、Base URL、模型 ID、请求参数、额度与服务状态。
先保存可复现信息
排查前记录发生时间、请求端点、模型 ID、HTTP 状态码、响应体中的错误信息和可公开的请求标识。分享日志时必须移除 Authorization、API Key、Cookie 和完整提示词等敏感内容。
- 400 或 422 通常先检查 JSON 结构、字段类型、消息角色以及模型是否支持所用参数。
- 401 先检查请求域名、Bearer 格式和 API Key 状态；403 还要核对模型或分组权限、钱包余额与订阅额度，并以错误 code 和响应内容为准。
- 404 或 model not found 先核对 Base URL、接口路径，并通过 /v1/models 重新取得精确模型 ID。
- 429 先检查访问频率、并发数和 Retry-After 提示，再按客户端策略降低请求速率。
- 500、502 或 503 需要用最小请求区分临时服务异常、模型可用性、超时与特定请求内容。
推荐排查顺序
- 确认请求发往 https://kunai.one，并检查 SDK 最终生成的完整接口路径是否符合预期。
- 使用同一 API Key 请求 /v1/models；若这一步失败，先解决鉴权、额度或网络访问问题。
- 选择列表中可见的模型，发送不带附件和工具的短消息，建立可重复的最小请求。
- 逐项恢复流式输出、历史消息、附件、工具和结构化参数，定位首次出现错误的变化。
- 查看用量记录和请求状态后再决定是否重试；结果不明确时避免无限重试或并发放大。