> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Fix sign-in, approval, missing tools, workspace, limit and pending problems with the MCP server
When a tool call fails, Alura returns an error your assistant can read: a `code`, a `suggestion` and whether to retry (`retryable`), plus `retry_after_seconds` when waiting helps. Most assistants act on it by themselves. This page is for when they can't. Every code links to its page in [Errors](/api-reference/errors).
## Sign-in and 401 errors
Alura answers `401` with a `WWW-Authenticate` header, and the assistant should start the sign-in again. It happens when:
* **The connection was disconnected**, in **Settings** > **Connected apps**, or a workspace owner removed its last workspace.
* **It wasn't used for 30 days.** Access lasts 15 minutes and the assistant renews it by itself, but the renewal expires after 30 days without use.
* **The account was suspended.**
To reconnect:
* **Claude.ai and Claude Desktop:** **Customize** > **Connectors**, then **Connect** next to Alura.
* **Claude Code:** run `/mcp`, pick **alura** and sign in. If that doesn't help, `claude mcp remove alura` and [add it again](/connect-ai).
* **ChatGPT and Cursor:** open the Alura plugin or server and connect again.
Sign-ins from an assistant work only on `https://mcp.alura.io/mcp`. Scripts calling `https://api.alura.io/v1` need an [API key](/api-reference/authentication).
The key was revoked, rotated more than 24 hours ago, or mistyped. Check it in **Settings** > **API** and send it as `Authorization: Bearer alura_sk_...`.
## The approval screen
| What you see | Why | What to do |
| - | - | - |
| This link has expired | The approval wasn't finished within 10 minutes | Go back to your assistant and connect again |
| Sign in again to continue | Connecting an app needs a sign-in from the last 10 minutes | Click **Sign in again** |
| We couldn't find your Alura account | Your sign-in has no Alura account set up yet | Sign in to platform.alura.io once, then connect again |
| Unknown app, Unverified | Alura hasn't verified this app | Continue only if you started the connection and the return address is your assistant's |
| Choose at least one permission | Every permission is unticked | Tick at least one |
| You're not a member of that workspace | You left the workspace, or were removed | Pick another workspace |
| Not available while viewing as a user | An Alura support session is active | Exit it and connect again |
When Alura creates a Free workspace for a new account, it also checks the email address:
| What you see | What to do |
| - | - |
| Verify your email address to get a free workspace | Verify it from Alura's email, then connect again |
| Use a permanent email address to get a free workspace | Sign up with a non-disposable address |
| A free workspace was already created for this email address | Join or create a workspace in Alura, then connect again |
| Too many new workspaces from your network | Try again tomorrow |
## Tools are missing or refused
The assistant sees only tools for the permissions you allowed on the approval screen. For example, without **Save research for you** there is no `add_to_saved_list`. To change permissions, disconnect in **Settings** > **Connected apps** and connect again. [Tools](/mcp/tools) lists which permission each tool needs.
`list_workspaces` and `switch_workspace` appear only if you're in more than one workspace.
In a ChatGPT workspace, ChatGPT keeps the tool list from when the plugin was published; an admin uses **Refresh** in the workspace's app settings to pick up new tools. On ChatGPT Pro, only tools that read are available, so saving research isn't.
A tool was called without its permission, usually because the assistant remembered it from an earlier connection. Connect again and allow the permission.
Sales history and keyword search history need the Growth plan or above. The refusal is free. Over MCP it says the plan is managed in Alura's settings, without a link; the workspace's owners can change it under **Settings** > **Plans**. Saving items also depends on the plan: Free workspaces can read saved research but not add to it.
## Workspaces
The connection has no current workspace, usually because you left it or an owner removed the app from it. Ask the assistant to list your workspaces and switch to one ("Switch Alura to my Wholesale workspace"). If you have no workspace left, the connection is revoked: connect again.
Each connection keeps its own current workspace, chosen on the approval screen. Switching workspace in the Alura app doesn't change it. Ask "Which Alura workspace are you working in?", then ask it to switch. A switch applies to every chat on that connection.
Saved research belongs to a workspace, so lists in another workspace appear after a switch. Private lists appear only to the person who created them. Global and public lists from the Alura app are not available over MCP.
A page cursor works only in the workspace that produced it. After a switch, ask for the list again from the first page.
## Limits
| Code | What happened | What to do |
| - | - | - |
| [`rate_limited`](/errors/rate_limited) | Too many calls this minute for the plan. A connection counts like an API key. | Wait `retry_after_seconds`, then retry |
| [`throttled`](/errors/throttled) | Reviews or products of many different shops or products in a short time. The workspace is slowed down for an hour. | Wait, then work more slowly |
| [`fetch_limit_reached`](/errors/fetch_limit_reached) | The day's limit for fetching items Alura has never seen | Wait `retry_after_seconds`. Items Alura already has still work. |
| [`credits_exhausted`](/errors/credits_exhausted), [`daily_credit_cap_exceeded`](/errors/daily_credit_cap_exceeded) | Out of API credits for the month or the day | See [API credits over MCP](/mcp/credits#monthly-and-daily-limits) |
[Rate and fetch limits](/api-reference/rate-limits) has the numbers per plan.
## Pending items
For now, Alura answers only with products, shops and keywords it already has. One it hasn't seen answers `fetch_unavailable`, free. In a batch, the items Alura has come back in the results and the rest are listed in `unfetched`, each with a `code` and `retry_after`. Only returned items are charged.
When Alura starts fetching new items from Etsy on request, the server will wait up to 20 seconds for a product or keyword. If it isn't ready, or it's a shop, which takes minutes, the tool will answer with `"status": "pending"`, `retry_after_seconds` and a suggestion to call again with the same arguments, free. Batches will list those items in `pending`.
| Code | Meaning |
| - | - |
| [`fetch_unavailable`](/errors/fetch_unavailable) | Alura can't fetch new items from Etsy right now. Items it already has still work. Retry later. |
| [`not_found_on_etsy`](/errors/not_found_on_etsy) | Etsy has no such listing or shop. Check the ID or link. |
| [`shop_opted_out`](/errors/shop_opted_out) | The shop asked Alura not to track it. Its data isn't available. |
| [`not_found`](/errors/not_found) | Alura doesn't have it, or it's a [mature listing](/mcp/tools#mature-listings), which assistants don't see. |
## Still stuck
Every tool result carries a `request_id` in `_meta`. Send it to Alura support from the app, with the time and the assistant you used.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.