> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix Quotable MCP connection problems: OAuth sign-in, every authentication message, scope and brand errors, rate limits, wrong methods and transports, and clients that don't send headers.

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.

> [!TIP]
>
> 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:

```json theme={"system"}
{
  "type": "/api/v1/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unknown API key.",
  "instance": "urn:request:7d0c9f3e-2b1a-4c8d-9e6f-5a4b3c2d1e0f"
}
```

Your client may show only "401" or "Unauthorized". If it has logs, the `detail` tells you which case you hit.

> [accordion] Sign in with OAuth, or send an API key as Authorization: Bearer quotable\_live\_….
>
> No credential arrived. A client that signs in starts the OAuth flow from here; see [OAuth sign-in](#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.

> [accordion] Unknown API key.
>
> 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.

> [accordion] This API key was revoked.
>
> 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.

> [accordion] This API key has expired.
>
> The key reached its expiry date. Create a new key and update the client. Keys can't be extended.

> [accordion] The API key creator no longer has the required access.
>
> 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.

> [accordion] Unknown access token. / The access token expired. / This access was revoked. / The access token was not issued for this server.
>
> 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.

> [accordion] The person who approved this connection no longer has the required access.
>
> 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

> [accordion] The client asks you to 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](https://docs.usequotable.com/mcp-server/overview.md#connect-your-client).

> [accordion] Only the owner or an integration admin of … can connect apps.
>
> 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**.

> [accordion] This request expired / This sign-in request expired or was already used.
>
> Approval links last ten minutes and work once. Start the connection again from the client.

> [accordion] Unsupported sign-in method / Secure sign-in required / Wrong server
>
> 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.

> [accordion] Your workspace changed since this page loaded.
>
> You switched workspace in another tab while the approval page was open. Reload the page, check the workspace it shows, and allow access again.

> [accordion] Unverified app, or a warning that the app uses a well-known name
>
> 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.

> [accordion] Untrusted return address / Unknown app / Incomplete request
>
> 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.

> [accordion] For your security, sign in again before doing this.
>
> 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.

> [accordion] The client keeps asking you to sign in again
>
> 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.

> [accordion] Sign-in works but tools return insufficient\_scope or not\_found
>
> 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.

> [accordion] insufficient\_scope: This tool requires the … scope, which the key was not granted.
>
> 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](https://docs.usequotable.com/mcp-server/authentication.md#scopes-by-tool).

> [accordion] not\_found: No such brand in this workspace, or the key's project allowlist does not include it.
>
> 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.

> [accordion] invalid\_cursor: The cursor is not one this server issued; start from the first page.
>
> The `cursor` was edited, truncated or taken from a different tool. Call the tool again without `cursor` and follow `next_cursor` from there.

> [accordion] invalid\_parameter: …
>
> 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.

> [accordion] MCP error -32602: Input validation error: Invalid arguments for tool …
>
> 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.

> [accordion] unavailable: Agents are not enabled for this workspace.
>
> The agent tools work only when Agents are turned on for your workspace. The other tools are unaffected.

> [accordion] forbidden: … (from run\_agent)
>
> 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.

> [accordion] rate\_limited: Too many runs started with this credential. …
>
> `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.

> [accordion] conflict: …
>
> An `idempotency_key` was sent again with different inputs. Use a new key for a new run.

> [accordion] internal: Something failed on our side. Request id ….
>
> An unexpected error on Quotable's side. Retry once. If it keeps happening, contact support with the request id from the message.

## HTTP errors

| Status | What you see | Cause and fix |
| - | - | - |
| `429` | `Rate limited` | The key or connection used its 300 requests for the current minute (a key's count includes its REST API calls). Every MCP request counts, including `initialize` and `tools/list`. Wait the number of seconds in `Retry-After`. See [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md). |
| `405` | `The MCP endpoint is stateless: POST JSON-RPC messages only.` | The client sent `GET` or `DELETE`. This happens when a client is set to the older SSE transport, or when you open the URL in a browser. Switch the client to Streamable HTTP (`"type": "http"`, or `httpUrl` in Gemini CLI). |
| `406` | `Not Acceptable: Client must accept both application/json and text/event-stream` | A custom script didn't send `Accept: application/json, text/event-stream`. MCP clients send it for you. |
| `415` | `Unsupported Media Type: Content-Type must be application/json` | Send `Content-Type: application/json`. |
| `413` | `{"error":"Invalid MCP request body"}` | The request body was too large. Tool arguments are short, so this usually means a client bug or a wrong endpoint. |
| `400` | `{"error":"Send one JSON-RPC message per request"}` | The client sent a JSON-RPC batch (an array). Send one message per request. |
| `400` | `{"error":"Invalid MCP request body"}` | The body isn't valid JSON. |
| `400` | `Bad Request: Unsupported protocol version: …` | The `MCP-Protocol-Version` header names a version the server doesn't support. Update your client, or leave the header out. |

> [!NOTE]
>
> 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

> [accordion] get\_visibility returns an empty data array
>
> 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.

> [accordion] search\_demand returns no terms
>
> 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`.

> [accordion] Only some of my data comes back
>
> 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`.

> [accordion] I can't see a brand
>
> 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.

> [accordion] The shopping tools return not\_found for a brand I 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.

> [accordion] list\_articles doesn't show documents from Quotable Agent
>
> Documents that Quotable Agent writes go to the Library, which `list_articles` doesn't read.

> [accordion] The assistant doesn't use Quotable
>
> 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:

```bash theme={"system"}
curl -i https://app.usequotable.com/api/mcp \
  -H "Authorization: Bearer $QUOTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A `200` with a list of tools means the key and network are fine. See [Other clients](https://docs.usequotable.com/mcp-server/connect/other-clients.md) for more raw requests.

> [card] [Authentication](https://docs.usequotable.com/mcp-server/authentication.md)
>
> Sign in with OAuth or create a key.

> [card] [Errors](https://docs.usequotable.com/api-reference/errors.md)
>
> The problem format shared with the REST API.

> [card] [Connect your client](https://docs.usequotable.com/mcp-server/overview.md#connect-your-client)
>
> Setup guides for each client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.