常见问题与故障排查

遇到问题时，按固定顺序检查，并保留状态码和脱敏后的响应正文。每次只修改一个变量，才能判断哪项改动有效。

通用排查顺序

1. 确认 API 基础地址来自控制台，没有重复路径。
2. 确认 API 密钥有效、无多余空格，并具备所需权限。
3. 确认模型名称与模型广场完全一致且当前可用。
4. 确认请求 JSON、消息格式和参数符合所选协议。
5. 确认账户有可用余额或额度。
6. 检查本机网络、代理、防火墙和平台状态。

常见错误

400：请求格式错误

检查 JSON 是否有效、字段类型是否正确、messages 是否为数组，以及当前模型是否支持所传参数。

401 / 403：鉴权或权限失败

重新确认 API Key、Bearer 鉴权格式和密钥权限。不要在工单中发送完整密钥。

404 或模型不存在

检查端点路径和模型名称；回到模型广场确认模型仍然可用，并复制名称而不是手动输入。

429：请求过多

降低并发和请求频率，采用指数退避重试；同时检查账户额度和平台限制。

5xx 或网络超时

稍后重试，减少单次请求的上下文与输出长度，并检查网络。避免无上限立即重试，以免放大故障和费用。

余额或额度不足

登录控制台检查余额、额度、计费状态和近期用量，再决定是否补充额度或更换低成本模型。

客户端有连接但没有内容

先关闭流式响应再测试；若非流式正常，更新客户端或检查其 SSE 处理能力。

提交问题时提供什么

• 问题发生的时间和时区。
• 端点路径与模型名称。
• HTTP 状态码和脱敏后的响应正文。
• 客户端名称、版本和操作系统。
• 是否启用了流式响应。
• 最小可复现请求，删除 API Key、个人信息和业务数据。

绝不要提供

完整 API 密钥、密码、支付信息或未脱敏的私有内容。