错误码与排查

排查错误时保留以下信息，但必须遮盖 API Key：

text

发生时间（含时区）
完整请求 URL
模型名
使用方案
HTTP 状态码
完整错误 JSON 或 HTML
request id
是否流式、是否已收到部分输出

常见状态码

状态码	常见含义	首要动作
`400`	参数或请求结构错误	对照目标协议检查字段，不要盲目重试
`401`	Key 缺失、无效或鉴权被拒绝	确认鉴权 Header、环境变量和 Key 状态；若偶发出现，请记录 request id
`402`	适用套餐额度不足或已耗尽	检查钱包中的套餐范围和剩余额度
`403`	账户、Key 或模型权限不足	记录 request id，确认 Key 使用方案和账户状态
`404`	URL、模型或接口不存在	检查 `/v1`、完整模型名和 endpoint
`413`	请求体过大	缩短会话、减少图片/附件或拆分请求
`418`	当前公网出口 IP 未加入访问白名单	检查本机 IP，在火箭开发微信群申请加入白名单
`429`	请求频率或服务容量受限	阅读错误正文，按 `Retry-After` 或指数退避重试
`500`	服务处理错误	保留 request id；有限重试后报告
`503`	当前方案暂时无法通过所选协议调用该模型	检查模型、方案和协议
`504`	网关或服务等待超时	保留完整响应和发生时间，有限重试后报告

典型错误：

text

No available channel for model MODEL under group PLAN,
endpoint: ENDPOINT

它表达的是三项条件没有可用交集：

text

模型 × 使用方案 × API 协议

按错误中原样显示的三项逐一核对。不要只因为 /v1/models 能看到模型，就假设所有协议和方案都能调用它。

出现 unexpected status 418，或响应是状态码为 418 的 HTML 页面时，先检查本机当前的公网出口 IP。切换网络、代理或 TUN 配置后，公网出口 IP 可能发生变化。

在火箭开发微信群中提供该 IP，请求将它加入白名单。不要在群里发送 API Key。白名单更新后，再从同一网络重新发起请求。