本页内容
通用报错
所有 Agent 工具接入 HiAPI 时都可能遇到的报错和处理方法。
各工具页的「常见问题」只写该工具特有的问题，下面这些所有工具都可能遇到。先看报错里的状态码或关键词，再对照下表：
| 报错 | 原因 | 处理 |
|---|---|---|
| 401 / invalid api key | Key 不完整、前后带了空格，或复制成了带星号的显示值 | 到 API 密钥 点复制图标重新复制完整的 HiAPI API Key |
| 报错里提到余额、额度或 quota | 账户余额不足，或这个 Key 设的额度上限用完了 | 到 账户余额 充值，或在 API 密钥页调高这个 Key 的额度上限 |
| 403 | 这个 Key 没有该模型的权限 | 确认 Key 的分组和权限，见 认证 |
| 404 / 模型不可用 | Base URL 多写或少写了 /v1，或模型名拼错 | 按 Base URL 与协议 核对地址；在 文本模型列表 复制模型名 |
| 400 does not support this endpoint | 工具选的协议这个模型不支持 | 换一种协议再试（例如 Claude 改用 Anthropic Messages），或换个模型 |
| 400 stream must be true / 一直转圈 | 模型只支持流式，工具发了非流式请求 | 在工具里打开流式输出；工具的「检测」「测试连接」按钮报这个错可以忽略，以实际对话为准 |
| 429 | 请求太频繁或并发太多 | 稍等再试，减少同时跑的任务；报错里提到额度的，按上面「余额、额度」一行处理 |
| 500 / 502 / 503 | 模型服务临时出错 | 稍等一两分钟再试；持续出现可以先换个模型，再联系我们 |
| 超时 / 响应中断 | 网络或代理拦截了长连接 | 检查到 api.hiapi.ai 的网络和代理规则后重试 |
重试之前先看调用记录
Agent 的一次任务可能已经在服务端跑完，只是工具这边断开了。重试前先到 调用记录 看这次请求有没有成功、扣了多少，避免同一件事重复付费。
还解决不了
到 联系我们 提交工单，附上下面这些信息，能更快定位：
- 出错的时间（精确到分钟）
- 用的工具和版本，例如 Claude Code 2.1.284
- 模型名和 Base URL
- 报错原文或截图
截图前把 API Key 遮住，不要把 Key 发给任何人，包括客服。