常见问题与排查

按错误码排查

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,通过企业方案页面或页面底部的联系方式联系我们。