Skip to main content
Most problems fall into four groups: sign-in doesn’t complete, the credential doesn’t reach the server, it reaches it but can’t read what was asked, or the client speaks a transport the server doesn’t serve. Find the message you see below.
Every response carries an X-Request-Id header, and errors include it as instance (urn:request:…). Quote it when you contact support.

Authentication errors (401)

Authentication failures return HTTP 401 with a problem body, before any tool runs. Every 401 also carries a WWW-Authenticate header with resource_metadata="https://app.usequotable.com/.well-known/oauth-protected-resource/api/mcp", which is how clients that sign in know where to go:
Your client may show only “401” or “Unauthorized”. If it has logs, the detail tells you which case you hit.
No credential arrived. A client that signs in starts the OAuth flow from here; see OAuth sign-in. If you meant to send a key, it didn’t arrive or the header isn’t in the form Bearer <key>. Check that:
  • The header name is Authorization and the value starts with Bearer followed by a space.
  • The key is complete: quotable_live_ plus 32 letters and digits, with no quotes, spaces or line breaks.
  • The environment variable your configuration references is set in the environment the client runs in. A GUI app started from the dock or Start menu may not see variables from your shell profile.
The key is well formed but doesn’t match any key. It may have been mistyped, or copied from a different workspace. Create a new key in Settings → API keys and copy it in full.
Someone revoked the key in Settings → API keys. Revocation applies to the next request, so a client that was working fails on its next call. Create a new key and update the client.
The key reached its expiry date. Create a new key and update the client. Keys can’t be extended.
The person who created the key left the workspace, or no longer has the role or brand access the key needs. Ask the workspace owner or an integration admin to create a new key.
The client sent an OAuth token that is unknown, past its hour, issued for another server, or belongs to a connection that was disconnected. A client that signs in refreshes on its own; if it can’t, it asks you to sign in again. Reconnect from the client.
Whoever clicked Allow access left the workspace, or no longer has the role or brand access the connection needs. Sign in again as the owner or an integration admin.

OAuth sign-in

That’s expected the first time: a client that supports MCP sign-in opens a Quotable page to approve it. Approve it there. If you meant to use an API key instead, the key didn’t arrive: check the header against your client’s guide in Connect your client.
Your role in that workspace can’t approve connections, the same rule as creating API keys. Ask the owner or an integration admin to connect, or switch to a workspace where you have that role with Use another workspace.
Approval links last ten minutes and work once. Start the connection again from the client.
The app’s sign-in request didn’t use the authorization code flow with PKCE, or asked for a server other than https://app.usequotable.com/api/mcp. Check the server URL in the app, update the app, or connect with an API key.
You switched workspace in another tab while the approval page was open. Reload the page, check the workspace it shows, and allow access again.
If you added Quotable in Claude or ChatGPT and see a warning, the request may not have come from them. Click Cancel and start again from the app.
The client asked Quotable to send you back to an address it didn’t register, isn’t registered with Quotable, or sent an incomplete request, so Quotable stopped instead of redirecting. Remove the connector in the client and add it again. Clients that return to a custom app link instead of an https or localhost address can’t sign in; use an API key with them.
Approving a connection needs a recent sign-in, like creating a key. Quotable signs you out and brings you back to the approval page after you sign in again, or asks for your second factor.
The connection was disconnected in Settings → MCP, the person who approved it lost access, its refresh token went unused for 30 days, or Quotable ended the connection to be safe. Sign in again. If it happens repeatedly, the client may be running in two places with one copy of its tokens.
The connection reads only the data and brands ticked on the approval page. Disconnect it under Connected apps and sign in again with what you need.

Tool errors

These come back as a tool result with "isError": true. The connection is fine; the call couldn’t be answered.
Your client lists every tool for any valid key or connection, but each call checks its scopes. Sign in again and tick that data, or create a new key: keys created in Settings → API keys include every scope. See scopes by tool.
The project_id isn’t a brand this key can read. Either the id is wrong (ask your assistant to call list_projects first), or the key is limited to other brands. A key’s or connection’s brands can’t be changed: create a new key, or sign in again, with the brand you need.
The cursor was edited, truncated or taken from a different tool. Call the tool again without cursor and follow next_cursor from there.
A value has the right form but can’t be used, such as a get_visibility range where from is after to, or one that spans more than 366 days. The message says which.
An argument doesn’t match the tool’s schema, such as a project_id that isn’t a UUID, a limit above 100, or a date not in YYYY-MM-DD form. The message lists each field. Most assistants correct this on their own on the next try.
The agent tools work only when Agents are turned on for your workspace. The other tools are unaffected.
The run can’t start from your client. Either the agent has steps that act outside Quotable, such as posting to Slack, so it runs only from the app, or the person who created the key or approved the connection has left the workspace or can no longer edit the brand. The message says which. Start the agent in the app, or reconnect as someone who can edit the brand.
run_agent was called many times in a short time. Wait the number of minutes in the message, and check that your assistant isn’t starting the same run in a loop. Pass an idempotency_key so a retried call doesn’t start a second run.
An idempotency_key was sent again with different inputs. Use a new key for a new run.
An unexpected error on Quotable’s side. Retry once. If it keeps happening, contact support with the request id from the message.

HTTP errors

The server never issues an Mcp-Session-Id, and it doesn’t need one back. If your client reports a missing session, it’s expecting a stateful server; any client that follows the Streamable HTTP specification works without one.

Results look wrong or empty

The series has one point per day with a tracking run. An empty array means no runs in the range: the brand is new, tracking is paused (paused: true in list_projects), or the dates are in the future. Widen the range or check the brand in Quotable.
The tool returns only demand terms Quotable has already measured for the brand’s prompts, and reading them never starts new research. A new brand may have none yet. Also check that location_code and language match the brand’s location exactly; language is a name such as English.
Lists return 20 items by default. Ask for more (“list all”, “the top 100”), and your assistant raises limit (up to 100) or follows next_cursor.
The key or connection is limited to other brands, or the brand belongs to another workspace. Run list_projects to see what it can read.
get_shopping_overview and get_shopping_product need a plan that includes Shopping. Without it they answer not_found, like a brand outside the key’s reach.
Documents that Quotable Agent writes go to the Library, which list_articles doesn’t read.
Check that the server shows as connected with its tools in your client, and that it’s turned on for the conversation. Then name it in your question: “Using Quotable, …”.

Still stuck?

Test the key outside your client with cURL. If this works, the problem is in the client’s configuration:
A 200 with a list of tools means the key and network are fine. See Other clients for more raw requests.

Authentication

Sign in with OAuth or create a key.

Errors

The problem format shared with the REST API.

Connect your client

Setup guides for each client.
Last modified on November 18, 2026