help.khb.com 常见问题 API 请求错误排查

API 请求错误排查

2026年6月14日2026年6月14日| 上午3:52
Categories:

API 错误码参考手册,帮助开发者快速定位并解决接口调用中的各类错误。

1. 尝试获取 HTTP 错误代码,初步定位问题

在代码中,尽量把错误码和报错信息(message)打印出来,利用这些信息,可以定位大部分问题。

HTTP/1.1 400 Bad Request
Date: Thu, 19 Dec 2024 08:39:19 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 87
Connection: keep-alive

{"code":20012,"message":"Model does not exist. Please check it carefully.","data":null}

常见错误代码及原因

错误码 原因 处理建议
400 参数不正确 请参考报错信息(message)修正不合法的请求参数
401 API Key 没有正确设置 检查 API Key 是否正确
403 账户余额不足或权限不够 权限不够最常见的原因是该模型需要实名认证,其他情况参考报错信息(message)
429 触发了 rate limits 参考报错信息(message)判断触发的是 RPM / RPD / TPM / TPD / IPM / IPD 中的具体哪一种,可以参考 Rate Limits 了解具体的限流策略
500 服务发生了未知的错误 请联系相关人员进行排查
503 / 504 服务系统负载较高 稍后尝试;对于对话和文本转语音请求,可以尝试使用流式输出(“stream”: true),参考 流式输出

2. curl 命令行测试

如果客户端没有输出相应的信息,可以考虑在命令行下运行 curl 命令(以 LLM 模型为例):

curl --request POST \
  --url https://khb.net.cn/v1/chat/completions \
  --header 'accept: application/json' \
  --header 'authorization: Bearer 改成你的apikey' \
  --header 'content-type: application/json' \
  --data '{
    "model": "记得改模型",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ],
    "max_tokens": 128
  }' -i

3. 可以尝试换一个模型,看看问题是否依旧

如果某个模型持续报错,可以切换到其他模型测试,判断是模型特定问题还是平台通用问题。

4. 如果开了代理,可以考虑将代理关闭后再尝试访问

部分代理软件(如 Charles、Fiddler 等)会拦截 HTTPS 流量,可能影响 API 请求。

5. 常见错误码处理建议

5.1 400 Bad Request

常见原因:模型名称错误、参数格式错误、消息结构不合法。

建议:仔细检查 model 字段是否在 模型广场 中存在;检查 messages 数组结构是否符合 OpenAI 规范。

5.2 401 Unauthorized

常见原因:API Key 未设置、错误或已过期。

建议:登录 KHB 平台 → API 密钥管理,确认 API Key 状态并重新生成。

5.3 403 Forbidden

常见原因:账户余额不足、模型需要实名认证、API Key 权限不足。

建议:充值账户余额;完成实名认证;检查 API Key 关联的权限范围。

5.4 429 Too Many Requests

常见原因:触发 Rate Limits(具体触发哪种指标需结合 message 字段判断)。

建议:实施指数退避重试机制;在客户端主动控制请求频率;错峰调用。

6. 追踪请求日志

API 响应头中包含 x-khb-trace-id 字段,提供该字段给 KHB 客服可快速定位请求链路日志。

7. 联系方式

如问题仍未解决,请通过 info@khb.com 联系 KHB 工程师,附上 x-khb-trace-id 和具体错误信息。

Related Post