错误排查
APIHub API 报错 401、404、429 怎么办？排查顺序与处理方法
更新于 2026/10/30 22:36:43
调用 APIHub 时，401 通常先查 API Key 与鉴权头，404 先查接口路径与模型 ID，429 先查请求频率和并发。不要对所有错误直接重复发送同一个请求；先阅读响应中的错误消息，再按原因处理。
状态码速查表
| 状态码 | 根据 APIHub 文档优先检查 | 建议处理 |
|---|---|---|
| 401 | Key 无效、禁用或过期 | 核对 Key 和鉴权方式，必要时更换有效 Key |
| 402 | 余额不足或 Key 额度限制 | 检查账户余额和 Key 限额 |
| 403 | 模型访问权限 | 检查 Key 的模型白名单与所选模型 |
| 404 | 路径错误、模型不存在或未启用 | 核对 Base URL、端点和模型 ID |
| 429 | 请求频率或并发限制 | 降低并发，按响应提示延后重试 |
| 500 / 502 | 网关或上游异常 | 保存错误信息，必要时有限重试或联系支持 |
上游或客户端也可能产生同一状态码。最终诊断要结合响应正文，不能仅凭状态码断定原因。
401：确认使用了正确的 Key
先确认填入的是 APIHub 控制台创建的 Key，而不是另一家服务的 Key。检查复制时是否多了空格或换行，并确认 Key 未被禁用、撤销或设为过期。
OpenAI 兼容请求使用 Authorization: Bearer ...；Anthropic 请求按文档使用 x-api-key。客户端如果自动添加前缀，避免手动再填一次 Bearer。
不要把 Key 发到公开群里求助。若已泄露，先撤销，再创建新 Key。
404：区分路径错误与模型错误
先看最终 URL。例如 Chat Completions 完整路径应为 https://api.apihub.ltd/v1/chat/completions，Messages 完整路径应为 https://api.apihub.ltd/v1/messages。
如果路径正确，再从模型价格页复制模型 ID，检查拼写、连字符以及该模型是否支持当前接口。模型展示名称不一定等于请求中的模型 ID。
429：避免立即无限重试
如果响应带有 Retry-After，优先遵循该提示；否则使用有上限的退避重试，并加入随机延迟，避免大量客户端同时重试。重试次数要有限制，同时降低请求频率或并发。
例如可以从较短等待开始，失败后逐步增加等待时间；具体间隔与次数取决于业务超时预算和服务限额，不应把示例间隔当作 APIHub 的固定规则。
超时：先确认请求是否已经执行
客户端超时不代表上游没有处理请求，也不代表没有产生费用。对于已经开始输出的流式请求，重试可能产生新的生成结果或重复业务操作。应记录请求 ID（若有）、已收到的内容和时间，再决定是否重新发起请求。
联系支持时提供什么？
提供请求时间与时区、客户端及版本、接口路径、模型 ID、HTTP 状态码、脱敏后的错误正文，以及请求 ID（若返回）。这些信息能帮助区分配置、权限、限流和上游故障。
通过联系页面提交问题。首次使用可先查看接入文档，再注册并创建 API Key。
资料核对日期：2026-10-30。错误码基础来源：APIHub 接入文档；重试和排查步骤为通用工程建议。