常见问题与排错

先记下发生时间、接口路径、模型、分组和请求编号。HTTP 状态码是线索，还需要结合错误文本；不同上游可能对相似问题返回不同状态码。

按状态码排查

状态或现象	常见原因	处理方式
400	JSON、字段、模型参数或内容长度不符合要求	退回最小文本请求，检查响应里的具体字段提示
401 / Invalid token	密钥缺失、无效、停用或过期	核对本站密钥、鉴权头及有效期，不要使用登录密码
402 / 余额相关错误	账户余额或请求额度不足，具体状态可能不同	检查钱包、密钥额度和预估用量，不要盲目重复充值
403	权限、模型限制、IP 限制或策略拒绝	核对分组与限制，保留错误信息
404	域名路径、接口类型或模型标识不匹配	检查重复 /v1，确认不是把网页地址当作接口
413	请求体过大	减少文本或附件，并确认模型的输入限制
429	频率、并发、上游额度或资源限制	降并发并等待；有 Retry-After 时参考它
500 / 502 / 503 / 504	网关或上游异常、超时或无可用资源	先检查服务状态，再有限重试，避免生成费用叠加
返回 HTML 而非 JSON	请求进入网页、代理或错误页面	核对完整路径、状态码和 Content-Type

网站能打开，为什么 API 不能用

网站页面、API 鉴权与上游模型生成是不同环节。网页能打开只能证明页面入口可访问。继续核对密钥、分组、模型、协议、额度和请求参数。

/v1/models 返回 200 也不是全部模型健康的证明，需要实际生成测试。未带密钥时返回 401 则是正常鉴权行为。

地址到底要不要加 /v1

看客户端怎样拼接路径：最终 Chat Completions 请求应是 https://api.cocoapi.top/v1/chat/completions。如果已经自动补 /v1，就不要再填一遍。完整规则见地址与核心概念。

同一个模型，为什么别人能用

模型名相同，不代表密钥分组、权限、参数和时间点相同。检查你自己的密钥；不要借用他人密钥测试。模型可能通过别名映射，必要时联系站方核实。

请求卡住或 SSL 超时

检查系统时间、网络、代理、DNS 缓存和客户端超时。可以对比不同网络，但不要把一次超时直接归因于代理或服务器宕机。

不要关闭证书校验、使用 HTTP 传输密钥，或把服务器 IP 直接替代 HTTPS 域名。服务器 IP 可能变化，证书也按域名匹配。

收到一部分文本后停止

可能是输出上限、正常结束、流式解析错误、客户端断连或上游故障。检查结束原因和日志。网络块不是完整事件；处理方法见流式输出。

客户端提示余额 0，但钱包有钱

第三方余额查询可能使用了错误接口、权限或货币换算。先在本站钱包和 API 密钥页面确认真实余额与限制。不要因余额插件报错就把管理员凭证填进工具。

还不能解决

使用支持信息模板整理问题。不要发送完整 API Key、密码、Cookie、付款二维码或含私人对话的完整日志。