错误排查

先保留 HTTP 状态码与响应中的具体错误信息。相同状态码可能由不同层返回，应结合正文判断；下面是排查方向，不是每个错误的唯一解释。

先检查这四项

1. 最终请求地址是否重复或遗漏 /v1。
2. 密钥是否来自豆子 API，是否有效、启用且有可用额度。
3. 模型 ID 是否完整，密钥分组是否允许访问。
4. 客户端使用的协议是否受目标模型与渠道支持。

用快速开始的最小请求复现。最小请求成功后，再检查客户端的额外参数。

按状态码定位

状态	常见方向	下一步
400	参数格式、模型能力、上下文超限	去掉可选参数，缩短输入，核对协议
401	密钥缺失、无效、到期或认证格式错误	检查密钥状态与 Authorization 头
403	分组、模型、来源或其他访问限制	查看具体错误，核对权限与限制
404	路径错误、接口不存在或资源不可见	核对最终 URL 和接口类型
429	速率、并发、额度或渠道限制	阅读正文区分原因，再降低请求或检查额度
500 / 502 / 503	网关或上游暂时异常	查看日志；对可重试错误做有限退避
504 / 客户端超时	处理耗时或连接等待超限	检查超时配置和输入长度，核对是否已产生记录

网络与流式问题

收到 HTML 而不是 JSON：检查是否请求到登录页、错误域名或代理错误页；API 请求应使用对应接口路径。

证书或连接失败：核对域名、HTTPS、系统时间及本机网络代理。不要把关闭证书校验作为长期修复。

一直等待、最后一次显示全部文本：检查客户端读取方式与自己代理层的响应缓冲，见流式输出。

网页报跨域错误：先用后端或本机脚本验证接口，把调用放到自己后端，避免把真实密钥暴露给网页访问者。

什么情况可以重试

认证、参数和权限错误，应先修正配置。临时网络失败、限流或部分服务端错误，可以在确认业务允许后有限重试，并遵循服务端提供的等待提示。

使用逐步增加等待时间的退避，并设置总次数上限。不要对所有错误无限循环；客户端、SDK 与业务代码同时重试，也可能放大调用次数。

反馈问题时提供什么

• 请求发生的时间与时区。
• HTTP 状态码、脱敏后的错误正文、请求 ID（如果有）。
• 模型 ID、分组、客户端名称与版本。
• 接口路径和可复现的最小请求结构。

删除密钥、Authorization 头、Cookie 和私人对话内容后再分享。可先在使用日志中核对记录，再使用控制台实际提供的联系入口。