Responses & errors

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

The envelope

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

{
  "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

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)
402	Not enough Credits	Top up — nothing was charged (Credits)
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)
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

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

{
  "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.

The envelopeCopy Anchor Link

The status says whether it was carried outCopy Anchor Link

A refusalCopy Anchor Link

On this page

The envelope

The status says whether it was carried out

A refusal