常见问题与排查
按错误码排查
401:鉴权失败
- Key 复制不完整,或者有多余的空格、换行。 重新复制一次。
- 用了
Authorization: Bearer传 API Key。 API Key 要放在请求头X-Api-Key里;Bearer只接受插件市场连接器签发的令牌。 - Key 已过期。 在 API Keys 页面查看状态,过期的需要新建。
- 示例命令里的变量没有展开。
'X-Api-Key: $AGENTEARTH_API_KEY'用了单引号,shell 不会替换变量,要改成双引号。
402:余额不足
充值后重试。可以先用查账户接口或 ae account 看当前余额。
403:Key 已停用或账号被封禁
- Key 已停用。 返回提示里会写明 Key 已被停用(MCP 客户端里是 JSON-RPC 错误码
-32004)。在 API Keys 页面重新启用即可,OAuth 授权的应用也一样,不需要重新授权。 - 账号被封禁。 联系客服处理。
400:工具不存在、参数错误
- "The requested tool does not exist or is temporarily offline":工具已下线,或
tool_url被改动过(其中的recommend_id改动任何字符都会失效)。重新推荐一次,或用工具详情拿到正确的tool_url。 - "The URL is incomplete: missing ... tool_name":执行地址里缺少
tool_name。 - "Invalid request body":请求体不是合法的 JSON,或者参数没有放在
params里。
405:请求方法不对
推荐和执行用 POST,浏览、详情、查账户用 GET。
429:调用太频繁
限流按每分钟调用次数计算,每个用户、每个 Key 分别计数。稍等一会儿再试;批量调用时控制并发。查询异步结果的 ae_get_result 不计入限流。
502:上游服务商不稳定
工具背后的服务商暂时出了问题。稍后重试,或者重新推荐,换一个同类工具。调用失败不扣费。
返回成功,但结果不对
error_no 为 0 只说明请求成功交给了工具,不代表一定拿到了想要的数据。先看 result 里的文字内容:
- 参数校验没通过:说明会写在结果文本里,按提示改参数。
- 上游没有查到数据:换个关键词、时间范围,或换一个同类工具。
- 有平台旁白(
platform_annotations):平台可能已经修正了参数,或建议换工具,按旁白处理。
异步任务查不到结果
- 返回
{"status": "not_found"}:任务号写错了,或者已经超过 24 小时被清理。需要重新提交任务。 - 一直是进行中:生视频等任务可能需要几分钟,继续轮询即可。不要重新执行原工具,否则会重复扣费。
MCP 连不上
- 检查地址是不是
https://agentearth.ai/mcp-server/,末尾的/不要省略。 - 传输方式要选 Streamable HTTP(配置里通常写
"type": "http"或"streamableHttp"),不支持旧的 SSE。 - API Key 在连接时校验,Key 错误会表现为连接失败。按上面"401"一节检查。
- 改完配置后,重启客户端或重新加载 MCP Server。
插件市场授权的问题
- 客户端突然断开:可能是在 API Keys 页面停用或删除了对应的「OAuth 授权的应用」。停用的重新启用即可,不需要重新授权;删除的需要在客户端里重新授权。
Agent 不调用 AgentEarth 的工具
在对话里明确写出「使用 ae ……」(ae 是 AgentEarth 的简称),比如"使用 ae 查询苹果公司的股价"。Agent 会优先通过 AgentEarth 推荐并调用工具。
还没解决?
带上请求时间、使用的工具名和返回的 error_msg,通过企业方案页面或页面底部的联系方式联系我们。
