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

# Troubleshooting

> What the common Rally MCP errors mean and what to do about them.

## The client cannot connect

**401 Unauthorized.** The key is missing, mistyped or revoked. Check the `Authorization: Bearer co_...` header in your client config, and that the key is still listed as active under **Settings → Agents & MCP**. OAuth clients get this when a session has expired and could not renew; sign in again.

**key\_has\_no\_roles.** You used an API key from **Settings → API keys** (those are for the [REST API](/developers/api)). Create an agent key under **Agents & MCP** instead.

**The client shows a warning about too many tools, or tools are missing.** Connect to a smaller set with a scope in the URL, for example `?profile=core`. See [Tools and scopes](/mcp/tools).

## The agent gets an error from a tool

Tool errors carry a code, a status and a hint the agent can read back to you.

| Status | Meaning | What to do |
| - | - | - |
| 402 | A plan limit was reached. | Upgrade under **Settings → Billing**, or wait for the monthly allowance to reset. |
| 403 | The key's role does not allow this. | Create a key with a wider role, or do that step yourself. |
| 404 | The id does not exist in this workspace. | The agent should list and try again; ids are never guessed. |
| 409 | The thing is not in the right state: already published, not live, already decided. | Have the agent read the record and adjust. |
| 429 | Too many calls: 600 a minute per key, 60 of them writes. | The agent slows down. If it happens often, the agent is polling; it should use `rally_wait_for`. |

## An action is stuck as pending

The agent asked for something that needs a person. Approve or dismiss it under **Settings → Agents & MCP → Agent requests**. An agent waiting on it continues once you decide. See [Approvals and roles](/mcp/approvals).

## The agent acts in the wrong workspace

An agent key belongs to the workspace it was created in. An OAuth session belongs to the workspace chosen at sign-in; sign in again and pick the right one, or connect a second server entry per workspace.

## Something else

Email [support@runrally.io](mailto:support@runrally.io) with the key name, the tool and the time. Every agent call is in your audit log, which is usually enough to see what happened.


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