返回与错误
每个工具都用同一种结构返回，HTTP 状态码说明调用是否被执行。
返回结构
每个工具——无论通过 MCP 还是 Tool API——都返回同样的三个字段：
{
"notification": { "message": "Found 12 unshipped orders.", "type": "success" },
"data": { "...": "the tool's result" },
"human_action": ""
}| 字段 | 是什么 | AI 怎么做 |
|---|---|---|
notification.message | 一句话说明发生了什么 | 转述给你 |
notification.type | success、info、warning 或 error | 据此判断结果 |
data | 结果本身——字段写在每个工具的输出 schema 里 | 用它继续工作 |
human_action | 只有你能做的事——重新授权店铺、充值 Credits。通常为空 | 转告给你 |
下一步该调用什么写在每个工具的描述里，从不写在返回结果里。
状态码说明是否执行了
- 200——调用已执行。
notification.type说明结果如何。执行了但结果不好——亚马逊拒绝的 Feed、失败的任务——仍然是 200，详情在data里。 - 4xx——调用没有执行。 什么都没有改变。被拒绝的调用绝不会是带
type: "error"的 200。 - 503——没有人能回应。 亚马逊、noon 或 SellerSheet 后端当时无法响应；按
Retry-After重试。Tool API 从不返回 502：公共入口会用自己的页面替换它的内容。
| 状态码 | 含义 | 怎么做 |
|---|---|---|
| 200 | 已执行——读取 data | — |
| 400 | 输入有误或缺少前提条件；亚马逊自己的拒绝也以 400 返回，亚马逊的错误列表在 errors 里 | 修正参数；不要原样重试 |
| 401 | 你的 SellerSheet 登录或密钥缺失、无效、已关闭或类型不对——从来不是亚马逊或 noon 的问题 | 重新登录或使用正确的密钥（密钥） |
| 402 | Credits 不足 | 充值——没有任何扣费（Credits） |
| 403 | 已登录但不被允许：店铺、站点、写权限、店铺已暂停 | 阅读那句说明，它会指出解决办法（掌控你的 AI） |
| 404 | 没有这个工具（Tool API）——改过名的工具会告诉你新名字 | 在工具目录里查找 |
| 429 | 套餐窗口或亚马逊配额已满 | 等待 Retry-After 秒 |
| 503 | 亚马逊、noon 或后端无法响应 | 按 Retry-After 重试 |
拒绝的结构
每一次拒绝，在每个工具上——包括表格、文档和 Drive 工具——都是同样的结构：
{
"notification": { "message": "…the sentence your agent reads to you…", "type": "error" },
"error_code": "rate_limit_exceeded",
"errors": null,
"human_action": ""
}notification.message——那句说明，它会指出解决办法。error_code——稳定的标识，供代码分支判断，例如rate_limit_exceeded、quota_exceeded或insufficient_credits。errors——亚马逊拒绝时是亚马逊自己的问题列表，否则为 null。把它和说明放在一起，不要压平成字符串。retry_after和Retry-After请求头——429 和 503 时需要等待的秒数。
每个 Tool API 响应还带有 X-Request-Id；联系支持时请附上它。
按现象查找所有解决办法：故障排查。