Troubleshooting - Alura API

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.

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.
ChatGPT and Cursor: open the Alura plugin or server and connect again.

A 401 on api.alura.io

Sign-ins from an assistant work only on https://mcp.alura.io/mcp. Scripts calling https://api.alura.io/v1 need an API key.

401 with an API key in the MCP config

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 doesn't see some tools

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

insufficient_scope

A tool was called without its permission, usually because the assistant remembered it from an earlier connection. Connect again and allow the permission.

plan_required

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

workspace_required

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.

The assistant works in the wrong workspace

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 lists are missing

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.

invalid_cursor after a switch

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`	Too many calls this minute for the plan. A connection counts like an API key.	Wait `retry_after_seconds`, then retry
`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`	The day’s limit for fetching items Alura has never seen	Wait `retry_after_seconds`. Items Alura already has still work.
`credits_exhausted`, `daily_credit_cap_exceeded`	Out of API credits for the month or the day	See API credits over MCP

Rate and fetch 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`	Alura can’t fetch new items from Etsy right now. Items it already has still work. Retry later.
`not_found_on_etsy`	Etsy has no such listing or shop. Check the ID or link.
`shop_opted_out`	The shop asked Alura not to track it. Its data isn’t available.
`not_found`	Alura doesn’t have it, or it’s a mature listing, 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.

​Sign-in and 401 errors

​The approval screen

​Tools are missing or refused

​Workspaces

​Limits

​Pending items

​Still stuck

Sign-in and 401 errors