AI clients & API
Every refusal says what went wrong and what to do. Here is each one, and its fix.
Every refusal carries a sentence in notification.message — your agent reads it to you — and, when only you can fix it, a note in human_action. The HTTP status says which kind it is (Responses & errors).
Signing in
| Symptom | What it means | Fix |
|---|---|---|
| "Unauthorized" (401) | Your sign-in or key is missing, expired, turned off or deleted — or it's the wrong kind (an MCP key on the Tool API, or the other way round) | Sign in again in your client, or create a new key under Settings → API & MCP |
| The browser never opens | The client is older than MCP sign-in | Update the client, or use an API key |
| Sign-in says you've reached your keys | Each browser sign-in creates an MCP key, and your plan's keys are all in use | Delete an unused key under Settings → API & MCP, or upgrade |
| 403 for a key that used to work | You are no longer an active member of the workspace the key belongs to | Ask the workspace owner, or use a key of your own |
Stores
| Symptom | What it means | Fix |
|---|---|---|
| Store ref refused (400) | The ref has no marketplace, like a bare myStore | Pass a ref with its marketplace, like myStore-US. The error lists every ref that works — or take one from get_user_context (Store refs) |
| "Store is paused" (403) | None of its marketplaces is active on your plan | Upgrade, or free a slot under My Stores → Edit Marketplaces (in the app: Settings → Stores & Marketplaces → Edit markets) |
| "No stores" | No store is connected yet, or none is shared with you | Connect your store |
| Ad tools come back empty | Ads was never authorized for that store | Ads on the store's row in Settings → Stores & Marketplaces |
| The store shows an authorization error | Amazon's authorization was revoked or expired | Reauthorize on Amazon on the store's row |
Permissions
| Symptom | What it means | Fix |
|---|---|---|
| 403 on a write tool | The key or your membership has read access on that store | Use a key with write access on it, or ask the workspace owner for it (Stay in control) |
| 403 on a store you can see in the app | The key is Restricted and that store isn't on its list, or its reach is one workspace | Add the store to the key, or use another key |
Limits and Amazon
| Symptom | What it means | Fix |
|---|---|---|
429 with Retry-After | A plan window is full, or Amazon's own quota for that operation | Wait the seconds Retry-After says, then retry (Credits & limits) |
| 402 | Not enough Credits for an image, copy or insights action | Top up on Settings → Billing & Credits — nothing was charged |
| 400 with Amazon's errors | Amazon refused the request — a wrong attribute, a missing field | Read errors: it is Amazon's own list; fix the input and send again |
| 503 | Amazon, noon or SellerSheet could not answer just then | Retry after Retry-After |
| A call times out | Some Amazon reports take a minute or two | Raise your client's MCP tool timeout; on the Tool API, run long workflows over MCP instead |
Sheets
| Symptom | Fix |
|---|---|
| Your agent can't write to your sheet | Open Google Sheets → Extensions → SellerSheet → Open Sidebar once to set up the workspace |
| A file "isn't yours" | Drive and sheet tools work only on files you own or that are shared with you, inside your workspace — share the file with your Google account |
Still stuck? Write to [email protected] with the time of the call.