使用帮助
错误排查
对照错误信息，检查接口地址、认证、模型与请求状态。
先检查这三项#
连接 api.onewonconnect.com 时遇到报错，先核对下面三项，再根据错误码与返回信息定位原因。
- 接口地址：确认客户端填写的是基础地址还是完整接口，避免重复的
/v1/v1或遗漏路径。 - API Key：确认复制完整、没有多余空格，且账号、Key 状态和可用额度正常。
- 模型名称：使用控制台中的完整模型 ID，确认该 Key 有权限使用，并选择对应的接口协议。
需要重新核对配置时，可查看 Codex、Claude Code，或返回 工具接入目录。
错误码速查#
优先阅读响应中的 error_code、error_message 或 error.type、error.message。同一状态码可能对应不同原因。
下表列出常见错误信息示例，具体措辞会因接口和上游而不同。平台、分组或客户端限制仅在返回相应提示时适用，请以控制台与实际响应为准。
| 状态 / 类型 | 错误信息示例 | 排查方法 |
|---|---|---|
400 / api_error | API key group platform is not gemini | Key 所属平台与请求协议不匹配。检查 Key 类型和客户端协议；如果使用 Gemini 接口，请先确认账号已开通对应协议。 |
| 400 / 请求参数错误 | invalid_request_error | 检查模型名、必填参数、消息格式和工具调用参数；可先新建对话，用一条简短消息测试。 |
| 401 / 认证失败 | Invalid API key / invalid_api_key | 检查 Key 是否有效、复制完整，以及客户端实际读取的认证配置。更新 Key 后重新启动客户端。 |
401 / api_error | User account is not active | 账号未激活或被停用。核对控制台账号状态，仍有疑问时联系管理员。 |
403 / api_error | This group is restricted to Claude Code clients (/v1/messages only) | 若返回此提示，当前 Key 的分组限制了客户端或协议。按分组要求使用 Claude Code，或更换支持当前客户端的 Key。 |
403 / api_error | Access denied. Your IP is <ip> | 当前出口 IP 受到访问限制。核对网络和 IP 白名单设置；持续出现时，提供错误信息供管理员核查。 |
404 / api_error | Model "<name>" is not available in this group | 当前分组没有可用的该模型。核对完整模型 ID、大小写以及 Key 的模型权限。 |
| 404 / 路径不存在 | Not Found | 检查最终请求地址，而不只是客户端输入框。确认没有重复 /v1，且所选协议与接口路径一致。 |
429 / rate_limit_error | Too many pending requests, please retry later | 排队或并发请求过多。降低并发和重试频率，按响应中的限制提示等待后重试。其他 429 还需检查用量和额度。 |
500 / api_error | Service temporarily unavailable | 当前请求没有可用的服务资源。稍后重试，或改用账号中另一个可用模型；持续失败时反馈请求信息。 |
502 / api_error | Upstream request failed | 上游请求失败。稍后重试；若持续出现，记录请求时间、模型和请求 ID。 |
502 / api_error | Upstream stream ended without a response | 上游在开始返回内容前中断。等待后重新发起请求，并检查客户端网络或超时设置。 |
503 / api_error | This group only supports Claude Code clients | 若返回此提示，应先修正分组与客户端的匹配关系。使用 Claude Code 或更换适用的 Key，单纯重试通常无法解决。 |
| 200 / 流式错误 | Recovered upstream error 502/403/429/500 | HTTP 连接建立后，流式输出仍可能中断。已收到的内容可能不完整，需要检查流中的错误事件与结束状态。 |
接口地址对照#
不同工具会自动补充不同的路径。基础地址与完整请求地址请分开核对：
| 接口协议 | 基础地址 | 最终请求地址 |
|---|---|---|
| Responses（Codex） | https://api.onewonconnect.com/v1 | https://api.onewonconnect.com/v1/responses |
| Chat Completions | https://api.onewonconnect.com/v1 | https://api.onewonconnect.com/v1/chat/completions |
| Anthropic Messages（Claude Code） | https://api.onewonconnect.com | https://api.onewonconnect.com/v1/messages |
以上为接口路径对照。客户端字段请以对应接入指南为准，例如 Continue 的 Anthropic apiBase 需要包含 /v1/，与 Claude Code 的根地址填写方式不同。
重试与流式中断#
- 先区分原因：认证、模型权限、协议或分组限制应先修正配置；临时服务异常再尝试重试。
- 逐步延长间隔：遇到限流或临时 5xx，可按 2 秒、4 秒、8 秒逐步退避，并限制总次数；响应包含
Retry-After时优先遵循该值。 - 减少并发：暂停重复任务和自动连续重试，避免多个客户端同时占满请求队列。
- 确认输出是否完整：HTTP 200 不代表流式生成已成功结束。中断后先检查已执行的工具操作，再决定是否重试，避免重复执行。
反馈问题#
排查后仍无法恢复时，请提供以下信息，便于定位：
- 请求时间及所在时区。
- 客户端名称、版本、模型 ID 与接口路径。
- HTTP 状态码、完整错误信息，以及响应中存在的请求 ID。
- 是否可以稳定复现、已尝试的处理步骤，以及脱敏后的配置或截图。
反馈前请隐藏 API Key、Authorization 等认证内容。不要发送完整的
auth.json 或包含密钥的配置文件。