文档快速开始站内基础教程
常见报错码
遇到状态码时，先判断问题类型，再按优先级排查
很多人一看到报错就开始怀疑平台有问题，但实际上，MoleAPI 接入中的大多数错误都可以通过状态码 + 配置项快速定位。
最推荐的排查思路
不要一上来就全盘推翻配置。建议先按这个顺序判断：
- 先看状态码是多少
- 再判断是身份问题、权限问题、地址问题，还是请求内容问题
- 最后回到控制台检查对应配置
错误码速查
| 状态码 | 常见含义 | 你应该优先检查什么 |
|---|---|---|
| 400 | 请求参数错误 | JSON 结构、字段类型、模型是否支持该参数 |
| 401 | 认证失败 | API Key 是否正确、是否多了空格、是否已失效 |
| 403 | 权限不足 | 模型权限、分组、IP 白名单、Key 限额 |
| 404 | 地址或路由错误 | Base URL 是否正确、是否漏了 /v1、路径是否拼错 |
| 429 | 限流或额度问题 | 请求频率、并发、余额、配额或限额是否触发 |
| 500 | 服务端异常 | 先重试并保留请求信息，持续出现再联系支持 |
分状态码理解
400：请求本身有问题
这种错误通常说明：
- 你的请求结构不对
- 某个字段类型不对
- 你给模型传了它不支持的参数
如果你最近刚换了模型、换了 SDK、或者复制了别人的示例代码，优先先看这里。
401：API Key 有问题
优先检查：
- 你填的是不是 MoleAPI 控制台创建的
sk-... - 前后有没有空格
- 有没有复制不完整
- 是否误把其他平台的 Key 填进来了
403：能访问接口，但没有权限这么做
这种错误最常见于：
- 当前 Key 没有该模型权限
- 当前分组不支持这个模型
- 设置了 IP 白名单，但来源 IP 不匹配
- Key 本身额度或限制被触发
404：地址错了
这是新手最常见问题之一。
优先检查：
- Base URL 是否填写成
https://api.moleapi.com/v1 - 是否仍在请求
api.openai.com - 是否把完整接口路径错误地填成 Base URL
429：被限制了，或者额度不够了
看到 429 时，不要只想到“请求太快了”，还要同时检查：
- 余额是否不足
- Key 是否有限额
- 是否并发过高
- 是否在短时间内请求太密集
500：服务端异常
如果是偶发的，可以先重试；如果是稳定复现的，建议保留：
- 请求时间
- 模型名
- 请求参数
- Request ID（如果客户端有）
这样后续排查会快很多。
一个非常实用的排查顺序
当你不知道从哪开始时，按这个顺序最省时间：
- 看状态码
- 看 Base URL
- 看 API Key
- 看模型名
- 看分组 / 权限 / 限额
- 看余额和日志
经验法则
404 多半先看地址；401 多半先看 Key；403 多半先看权限；429 不仅看频率，也要看余额与限额。
下一步建议看什么
这篇文档对您有帮助吗？
最后更新于