API 错误码与故障排查
这是开发者和 API 用户的统一排查页。遇到“打不开”“不能用”“报错”“连接失败”“请求失败”“一直转圈”或“超时”，先根据状态码和第一检查项定位。
快速判断
| 报错 | 第一检查项 |
|---|---|
| 400 Bad Request | 请求参数 / 请求体 / 模型 |
| 401 Unauthorized | API Key / 认证信息 |
| 403 Forbidden | 权限 / 分组 / 模型访问 |
| 404 Not Found | Base URL / Endpoint / /v1 路径 |
| 408 Request Timeout | 网络 / 等待时间 |
| 409 Conflict | 请求状态或资源冲突 |
| 429 Too Many Requests | 请求过快 / 限流 / 并发 |
| 500 Internal Server Error | KCO 服务端异常 |
| 502 Bad Gateway | 上游 / 网关 |
| 503 Service Unavailable | 服务暂时不可用 |
| 504 Gateway Timeout | 上游响应超时 |
400 Bad Request
请求已经到达接口，但请求体或参数不符合要求。常见原因：JSON 格式错误、必填参数缺失、模型名称错误、参数类型错误，或把 Chat Completions 请求发到了 Responses API Endpoint。
先检查请求体、模型名称、协议和客户端自动拼接的路径。不要用别的服务商示例直接替换 KCO 参数。
401 Unauthorized
通常表示 API Key 缺失、复制错误、已失效，或没有正确放进 Authorization: Bearer ...。重新从 KCO AI 控制台 → API 密钥复制 Key，确认没有空格或换行，并确认当前 Provider / 分组正确。
key错误、密钥错误、密钥无效、Unauthorized 都先按 401 处理。不要发送完整 Key；求助时只提供时间、客户端、模型和脱敏后的错误信息。
key无效
这类提示通常对应 401 Unauthorized。重新复制 KCO API Key，检查 Key 状态、分组和环境变量；不要把真实 Key 发给任何人。
403 Forbidden
认证信息可能有效，但当前 Key 或分组无权访问目标模型、工具或接口，或者请求受到权限策略限制。检查 Key 所属分组、模型权限和图像/MCP 能力是否已开通；不要反复更换 URL。
404 Not Found
常见原因是 Endpoint 写错、API 路径错误，或客户端自动拼接路径后形成错误地址。重点检查 /v1 是否重复或遗漏：普通 OpenAI-compatible 客户端通常使用 https://api.kcoai.com/v1，CC Switch / Codex 自动导入使用 https://api.kcoai.com。
408 Request Timeout
请求等待时间过长，可能是本地网络、代理或上游响应慢。先重试一次，检查网络和服务状态；复杂请求或大图片先降低并发、尺寸或输入长度。
409 Conflict
请求与当前资源状态冲突，例如重复提交或客户端持有过期状态。确认没有重复点击、重复创建任务或并行修改同一配置，刷新客户端后再试。
429 Too Many Requests
请求过于频繁、并发过高或触发 Key / 分组限流。稍后重试，降低并发和重试频率，并检查当前 Key / 分组的限制。不要用无限重试把限流变成更大的流量。
导入CCS没反应
这类提示属于 CC Switch 配置流程，不是 API 状态码。请直接查看 CC Switch 自动导入失败怎么办，按“只打开软件 → 回网页再点一次 → 图形界面手动添加”的顺序处理，不要连续快速点击。
500 Internal Server Error
服务端处理请求时出现异常。先重试一次；持续发生时记录时间、模型、请求类型、状态码和错误文本，联系 KCO 支持时不要提供 API Key、Cookie 或完整日志中的授权头。
502 Bad Gateway
网关没有从上游服务获得正常响应。常见情况包括上游模型临时异常、网络链路异常、上游连接中断，或中转服务暂时无法获得正常响应。
502 通常并不代表 API Key 填错。 建议按顺序：
- 重新请求一次。
- 等几十秒后再试。
- 如果有权限，换一个可用模型。
- 查看 KCO 服务状态和本地网络。
- 持续出现时联系客服，并提供时间、模型、请求类型和错误信息，不要提供 API Key。
Bad Gateway、网关错误、上游错误、上游异常、请求失败 都可以从这里开始。
503 Service Unavailable
服务暂时不可用，可能是上游维护、服务繁忙或临时容量不足。稍后重试，避免连续高频请求；持续发生再检查服务状态并反馈时间和模型。
504 Gateway Timeout
网关等待上游响应超时。稍后重试，降低并发；如果请求特别复杂、输入很长或图片很大，缩小请求后重新发起。长时间持续出现再联系客服。
Gateway Timeout、超时、一直转圈 可以直接搜索本页。
网络错误与客户端提示
“打不开”“不能用”“连接失败”“请求失败”不一定是 API 错误码。先确认：
- 能否访问
https://api.kcoai.com。 - 本机 DNS、代理、防火墙和企业网络是否拦截请求。
- 客户端是否把错误域名或错误端口写进配置。
- 是否在 IDE 中设置了和系统终端不同的环境变量。
- 是否在等待一个已经失败的请求；取消后重新启动客户端。
配置、模型与日志
模型不存在、模型用不了：检查模型拼写、Key 分组和当前可用模型列表。没有权限：按 403 检查分组和能力权限。额度不足：回到 KCO 控制台查看账户余额、Key 状态和分组额度。codex 不是内部或外部命令、找不到 codex：先安装 Codex CLI、检查 PATH，并重新打开终端。CCS打不开、CC Switch打不开、导入失败、只打开CCS、导入到CCS没反应：按 CC Switch 自动导入失败怎么办 操作，不要连续快速点击。config.toml/auth.json：按 KCO AI 开发者文档 的手动配置说明检查文件位置、TOML 键名和环境变量；KCO 自定义 Provider 不需要手写auth.json。OpenAI Official、切回自己的账号、自己的ChatGPT：按 切回自己的 ChatGPT / Codex 账号 操作。image tool、不能生图：先按 403 检查图像能力和分组，再按 400/429/502 检查参数、限流和上游。MCP：先确认普通 API 请求正常，再分开检查 MCP 命令、环境变量、权限和工具进程日志。
codex不是内部命令
先安装 Codex CLI，确认 Node.js、npm 和 PATH，再关闭并重新打开终端，运行 node --version、npm --version 和 codex --version。IDE 自带终端还需要单独重启或刷新环境。完整说明见 KCO AI 开发者文档。
提供什么日志
反馈时提供发生时间（含时区）、客户端/IDE、模型、请求类型、HTTP 状态码和脱敏后的错误文本。可以保留请求 ID（如果客户端展示），但必须删除 Authorization、API Key、Cookie、完整 auth.json 和包含隐私的提示词/文件内容。