错误排查

遇到错误时，先记下三样东西：请求时间、模型名、请求 ID（响应头里的 X-Request-ID）。不要连续重试，以免重复扣费，也会放大上游的波动。

按状态码查

状态码	常见原因	怎么处理
401	Key 缺失、写错，或已被删除；请求头不是 Authorization: Bearer <Key>	检查环境变量是否生效，在控制台确认 Key 仍然存在
403	账号分组没有该模型的权限，或 Key 设置了模型 / IP 限制	换一个你的分组能用的模型，或检查 Key 的限制设置
404	Base URL 写错（多了或少了 /v1），或模型名不存在	OpenAI 协议用 …/v1，Anthropic 协议只填到域名；模型名从模型广场复制
400	请求体格式不对，或参数不被该模型支持	先用最简请求（只带 model 和 messages）验证，再逐个加参数
429	请求太频繁或并发太高	降低并发、加指数退避；单 IP 每分钟有总体请求上限
余额不足	账户或 Key 的额度用完	到钱包充值，或调高这把 Key 的额度上限
5xx	上游渠道临时故障或超时	等几秒后重试一次；持续失败时换一个同类模型

流式输出中断

• 确认客户端按 SSE 逐行读取、持续读到结束，没有中途主动关闭连接，也没有被代理或网关缓冲。
• 单次请求最长可以持续 10 分钟；超过时请拆分任务，或降低 max_tokens。
• 在中国大陆网络下中断频繁时，换成国内直连地址 api-cn.heang.top。

连接慢或超时

• 国内网络优先用 https://api-cn.heang.top/v1。
• 写代码、长回答、图片和视频任务本来就要更久，客户端超时按任务类型设，不要所有请求共用一个很短的阈值。
• 用 curl -w "%{time_starttransfer}\n" 看首字节时间，区分是网络慢还是模型生成慢。
• 本机开了代理时，检查代理是否把 heang.top 的流量绕到了海外节点。

还是解决不了

带上请求时间、模型名、请求 ID、错误码、是否流式和报错原文联系站长，请求参数记得先脱敏。不要把完整的 API Key 发给任何人，包括站长。