# 返回与错误 (https://sellersheetai.com/zh/docs/mcp-api/responses)

> 每个工具都用同一种结构返回，HTTP 状态码说明调用是否被执行。



## 返回结构 [#返回结构]

每个工具——无论通过 MCP 还是 Tool API——都返回同样的三个字段：

```json
{
  "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 的问题 | 重新登录或使用正确的密钥（[密钥](/zh/docs/mcp-api/keys)）            |
| 402 | Credits 不足                                            | 充值——没有任何扣费（[Credits](/zh/help/app/settings/billing)） |
| 403 | 已登录但不被允许：店铺、站点、写权限、店铺已暂停                              | 阅读那句说明，它会指出解决办法（[掌控你的 AI](/zh/docs/mcp-api/control)） |
| 404 | 没有这个工具（Tool API）——改过名的工具会告诉你新名字                       | 在工具目录里查找                                             |
| 429 | 套餐窗口或亚马逊配额已满                                          | 等待 `Retry-After` 秒                                   |
| 503 | 亚马逊、noon 或后端无法响应                                      | 按 `Retry-After` 重试                                   |

## 拒绝的结构 [#拒绝的结构]

每一次拒绝，在每个工具上——包括表格、文档和 Drive 工具——都是同样的结构：

```json
{
  "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`；联系支持时请附上它。

按现象查找所有解决办法：[故障排查](/zh/help/troubleshooting/ai)。