常见错误与解决方法
先记录发生时间、模型名、HTTP 状态码和完整错误信息。同一个状态码可能有不同原因，响应中的错误说明比状态码本身更具体。
401：鉴权失败
常见提示：Invalid token、invalid_api_key、未提供令牌。
- 使用的是光迹 API 模型调用密钥，而不是登录密码或个人资料访问令牌。
- 已复制完整值，没有掩码、空格或多余换行。
- 密钥未过期、未禁用、未删除。
- HTTP 请求正确包含
Authorization: Bearer 你的密钥。
具体端点如果采用其他认证格式，应按对应接口说明填写。
403：访问被拒绝
检查密钥的模型限制、IP 白名单、账号和分组权限。权限拒绝也可能来自站点安全防护，应结合响应内容判断，必要时提供请求 ID 联系客服。
404：地址或模型不正确
- 检查域名、接口路径及请求方法。
- 排除
/v1/v1重复路径，以及误填控制台地址的情况。 - 模型不存在时，重新复制准确模型 ID，并确认当前分组可用。
返回 HTML 页面而不是 JSON 时，先检查地址和网络中间层。不要仅凭这一点判断一定是某一种故障。
429：请求受限
可能与请求频率、Token 速率、当前负载或上游限制有关。
降低并发和发送频率；响应含 Retry-After 时参考该值等待。重试应有次数上限，不要让客户端持续密集重试。持续发生时提供时间和请求 ID 给客服。
提示额度不足
依次检查账户余额、密钥剩余额度、密钥状态和有效期。如果使用订阅，再检查订阅可用额度、有效期与计费偏好。
账户余额足够，并不代表这把密钥一定有可用额度。见 管理密钥。
提示无可用渠道或模型不可用
先确认模型 ID、密钥分组和模型限制，查看平台公告。用户不需要去配置服务器渠道；核对后仍失败，请 联系客服 处理。
400：参数或上下文有误
检查 JSON 格式、必填字段、模型支持的参数和接口协议。提示上下文过长时，减少历史对话、附件或输出长度。可先用最小文本请求排除复杂参数影响。
超时、Failed to fetch 或 5xx
检查网络、DNS、代理和请求地址，稍后进行少量重试。浏览器应用还需检查 HTTPS 与跨域情况；正式应用应在服务端保存密钥并发起请求。
超时不等于请求没有执行。重试前留意已有结果和使用日志，避免重复提交产生额外消耗。
还是解决不了
把问题整理为 客服反馈模板，附上脱敏截图。不要发送完整 API 密钥。