文档
进入控制台
文档目录
本页目录

帮助

API 排错与安全

先用最小非流式请求判断基础 API 是否可用，再逐层恢复客户端、代理、流式和工具调用。错误格式、状态码、请求标识与重试策略以“错误与重试”页为准，本页专注定位方法和安全检查。

排错顺序

  1. 保留现场：记录请求发生时间、客户端及版本、模型、协议、是否流式、实际 URL 和完整错误；密钥与正文必须脱敏。
  2. 建立基线：用同一密钥和模型发送最小非流式 cURL，只保留一条文本输入。
  3. 判断边界：最小请求失败，先处理认证、权限、模型、协议或基础网络；最小请求成功，再检查客户端和代理。
  4. 逐项恢复：按客户端、流式、工具和业务参数的顺序，一次只恢复一项并记录结果。

最小请求

-i 会输出响应头和响应体，--max-time 可避免命令无限等待。记录响应实际返回的 X-Request-ID 和其他请求标识；不要把自行发送的 X-Client-Request-ID 当作唯一关联键，平台不承诺原样保留或返回这个自定义值。

cURL · Responses
curl -i --max-time 60 https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "请只回复：连接成功"
  }'

客户端使用 Chat Completions 时，用同一密钥和模型测试对应协议：

cURL · Chat Completions
curl -i --max-time 60 https://api.khaix.net/v1/chat/completions \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

HTTP 200、响应体包含文本，并且控制台出现对应调用记录，说明当前密钥、模型、协议和基础链路可用。模型 ID 可通过 GET https://api.khaix.net/v1/models 或模型广场确认。

先分类错误

错误与重试是错误响应、常见状态码、流内错误、请求标识和重试边界的统一参考。先按该页判断失败属于请求、认证、权限、额度、限流还是服务链路，再回到本页做环境对照。

查看错误与重试错误结构、状态码、流式失败、请求 ID 与生产重试策略

客户端、流式与网络

对照结果优先检查验证方法
cURL 成功，客户端失败provider、Base URL 拼接、配置作用域、缓存和额外参数查看客户端最终 URL 和请求体；重启后用新会话复测
直连成功，经过代理失败TLS 信任链、认证头转发、请求体上限、连接与空闲超时用同一请求分别直连和经过代理，对比状态码与响应头
非流式成功，流式失败SSE 解析、代理缓冲、读取超时和连接复用先用 curl -N 直连，再逐层加入代理和客户端
文本成功，工具调用失败模型能力、协议字段、工具参数序列化和结果回传先用一个无副作用工具，保留完整工具调用序列
  • 如果最终 URL 出现 /v1/v1 或重复 endpoint，把完整接口地址改为客户端要求的 Base URL。
  • 如果请求仍发往其他域名，自定义 Base URL 未在客户端实际运行的配置作用域中生效。
  • 如果失败总在固定时长发生，对比客户端、企业代理和反向代理的超时值，不要只增加单侧超时。
  • 流中断开不代表工具没有执行；重试有副作用的操作前，先核对业务状态和去重机制。

支持报告

可稳定复现后再整理报告。信息越接近一次具体调用，越容易定位；不要发送未经脱敏的完整配置或聊天记录。

  • 时间：请求发生的 UTC 时间和本地时区，精确到分钟。
  • 追踪：响应实际返回的 X-Request-ID、其他请求标识和控制台记录标识。
  • 环境：客户端或 SDK 名称、精确版本、操作系统，以及是否经过 WSL、容器、远程主机或代理。
  • 请求：模型 ID、协议、是否流式，以及已脱敏的实际请求 URL。
  • 错误：HTTP 状态码、完整错误消息；流式请求还需最后一个完整事件。
  • 对照：最小 cURL 是否成功，直连与代理、非流式与流式的结果是否不同。

安全基线

密钥

  • 应用、环境和团队分别使用独立密钥；怀疑泄露时立即撤销并轮换。
  • 密钥放在环境变量、系统钥匙串或部署平台 Secret 中，不提交到仓库，也不放进浏览器前端或公开脚本。
  • 日志默认隐藏 Authorization header 和认证配置，并限制调试日志的访问与保留期限。

执行

  • 编码 Agent 的文件修改、命令执行、联网和外部工具权限应与任务风险匹配；不可信项目保留人工确认。
  • 高风险任务使用低权限账户、容器或虚拟机，并限制工作目录和凭据可见范围。
  • 流式断开或客户端自动重试前，先确认工具和外部操作是否已经执行。

代理

  • 本地协议转换器、调试代理和未认证端口只在受控网络开放。
  • 企业代理和自建反向代理需要验证 TLS、限制管理端口，并关闭 Authorization 与正文记录。
  • 证书问题应修复信任链，不应通过关闭 TLS 校验绕过；排错结束后移除临时抓包证书和全局代理。

数据

  • Prompt 和模型响应会在请求期间由 KHaiXAPI 与对应模型服务处理，请移除与任务无关的凭据和个人信息。
  • 正常请求正文不会写入 KHaiXAPI 的业务存储或业务备份；请求链路中的即时处理、调用与计费记录，以及诊断、安全、你主动提交的客服材料或法律要求等特殊情形见隐私政策。
  • 第三方客户端可能自行保存会话、遥测或日志，使用前检查其数据设置和存储位置。
  • 生产系统应为输入、输出和工具执行设置权限控制、校验、审计与保留期限。