# Responses & errors (https://sellersheetai.com/docs/mcp-api/responses)

> Every tool answers with the same envelope, and the HTTP status says whether the call was carried out.



## The envelope [#the-envelope]

Every tool — over MCP and over the Tool API — returns the same three fields:

```json
{
  "notification": { "message": "Found 12 unshipped orders.", "type": "success" },
  "data": { "...": "the tool's result" },
  "human_action": ""
}
```

| Field                  | What it is                                                                     | What your agent does |
| ---------------------- | ------------------------------------------------------------------------------ | -------------------- |
| `notification.message` | One sentence saying what happened                                              | Tells you            |
| `notification.type`    | `success`, `info`, `warning` or `error`                                        | Weighs the result    |
| `data`                 | The result itself — its fields are in each tool's output schema                | Works with it        |
| `human_action`         | Something only you can do — reauthorize a store, top up Credits. Usually empty | Passes it on to you  |

What to call next is in each tool's description, never in the result.

## The status says whether it was carried out [#the-status-says-whether-it-was-carried-out]

* **200 — the call was carried out.** `notification.type` says how it ended. A call that ran and ended badly — a feed Amazon rejected, a job that failed — is still 200, with the detail in `data`.
* **4xx — the call was not carried out.** Nothing changed. A refused call is never a 200 with `type: "error"`.
* **503 — nobody could answer.** Amazon, noon or SellerSheet's backend could not answer just then; retry after `Retry-After`. The Tool API never answers 502: the public edge would replace its body with its own page.

| Status | Meaning                                                                                                             | What to do                                                                     |
| ------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 200    | Carried out — read `data`                                                                                           | —                                                                              |
| 400    | Bad input or a missing precondition; Amazon's own refusal comes back as 400 with Amazon's list in `errors`          | Fix the arguments; don't retry as is                                           |
| 401    | Your SellerSheet sign-in or key is missing, invalid, turned off or the wrong kind — never an Amazon or noon problem | Sign in again or use the right key ([Keys](/docs/mcp-api/keys))                |
| 402    | Not enough Credits                                                                                                  | Top up — nothing was charged ([Credits](/help/app/settings/billing))           |
| 403    | Signed in, but not allowed: the store, the marketplace, write access, a paused store                                | Read the sentence; it names the fix ([Stay in control](/docs/mcp-api/control)) |
| 404    | No such tool (Tool API) — a renamed tool says its new name                                                          | Look it up in the catalog                                                      |
| 429    | A plan window or Amazon's quota is full                                                                             | Wait `Retry-After` seconds                                                     |
| 503    | Amazon, noon or the backend could not answer                                                                        | Retry after `Retry-After`                                                      |

## A refusal [#a-refusal]

Every refusal, on every tool — the sheet, doc and Drive tools included — has the same body:

```json
{
  "notification": { "message": "…the sentence your agent reads to you…", "type": "error" },
  "error_code": "rate_limit_exceeded",
  "errors": null,
  "human_action": ""
}
```

* `notification.message` — the sentence; it names the fix.
* `error_code` — a stable identifier your code can branch on, such as `rate_limit_exceeded`, `quota_exceeded` or `insufficient_credits`.
* `errors` — Amazon's own list of problems when Amazon refused, otherwise null. Keep it next to the sentence; never flatten it into a string.
* `retry_after` and the `Retry-After` header — seconds to wait, on 429 and 503.

Each Tool API response also carries `X-Request-Id`; quote it when you write to support.

All the fixes, by symptom: [Troubleshooting](/help/troubleshooting/ai).