Troubleshooting

Common problems connecting to or using the Raken connector, and how to fix them. If you're just getting set up, start with the Setup & Usage Guide.

Connection & sign-in

• Sign-in page doesn't load. Check that your network can reach Raken, then try connecting again. If the page still doesn't load, contact Raken support.
• Connector connects, but the first tool call returns 401 / "Raken account not linked." Disconnect and reconnect the connector to re-run the sign-in flow.
• Tools return empty lists. You may have signed into a different Raken account than expected. Confirm you signed in with the account that holds your projects and crew.

Raken connection expired — reconnect required

The connector worked before, but now a tool call stops and your AI assistant asks you to re-authorize with Raken (for example, a message that your Raken connection has expired with a prompt to reconnect or re-authenticate).

This means the stored Raken sign-in (the refresh token the connector keeps on your behalf) is no longer valid, so the server can't get a fresh Raken access token to make the call. The connector detects this and asks you to sign in again rather than failing silently. Common reasons:

• You signed in elsewhere too many times. Raken allows a limited number of active connections per user. When you authorize a new connection (another device, another AI assistant, or a fresh reconnect) beyond that limit, Raken removes the least recently used connection — which may be the one this connector was using.
• The sign-in simply aged out, or someone revoked the connector's access from the Raken side.

What to do: re-run the Raken sign-in for the connector — follow your AI assistant's reconnect / re-authenticate prompt, or disconnect and reconnect the connector from its settings to re-run the OAuth sign-in. Once you finish signing in, retry the request — it should go through.

Error messages

When a tool fails, your AI assistant shows the message it got back. Most come from Raken and a few HTTP statuses get a clearer, actionable message instead of Raken's raw response; one (the per-connection rate limit below) comes from the connector itself. Here's what each one means and what to do.

403 — "Raken MCP access isn't turned on for your company"

You signed in successfully, but your Raken account isn't entitled to use the Raken MCP connector, which every tool except get_user_info requires.

Raken MCP access is enabled by Raken, per company — it isn't on by default. The connection itself is fine: get_user_info keeps working (it confirms which account you're signed in as), while every data tool comes back with this error.

What to do: contact Raken support to have Raken MCP access enabled for your company, then try again. This is enabled on Raken's side, not something a reconnect or a different prompt will fix.

429 — "Raken's API is rate-limiting this request"

Raken enforces three limits, and all of them return a 429. The message you get names which one, so read it before acting — the fix is different for each. This one and the next are Raken's account limits; the third is the connector's own per-connection limit (it mentions "this MCP server").

This is a short-window limit: too many requests in the same second, or too many at the same moment. It's sized by your plan, and the allowance is shared with every other integration on the account — so it can trip even when your AI assistant is already working one step at a time.

What to do:

• Wait a few seconds and continue. This limit clears on its own; you don't need to change anything.
• Pick up from the item that failed rather than restarting the whole batch, so the work already done isn't repeated.
• If it happens often, avoid running many requests at once (e.g. don't ask your AI assistant to page through a huge list as fast as possible). The connector does ask the AI assistant to make its calls one at a time, but that's guidance rather than a hard stop, so it's worth saying explicitly when you're working through many records.

429 — "Raken's daily API quota is exhausted"

The account has used up its total requests for the day. This is a different limit from the one above, and waiting a few seconds will not help — nothing succeeds until the allowance resets.

• The quota is shared across every user and integration on the account, so it is often used up by something other than what you were doing.
• It resets at 00:00 UTC. That's around midday in New Zealand and afternoon or evening in the US — so depending on where you are, you may get it back later the same working day rather than tomorrow.

What to do:

• Stop retrying. Repeated attempts can't succeed before the reset.
• Check what succeeded before the failure, so you know what still needs doing once the quota is back.
• The quota is sized by your plan, so if the account regularly runs out, contact Raken to raise it.

If a 429 says it couldn't tell which limit was hit, treat it like the quota case — stop rather than retrying. That's the safe reading: if it turns out to have been the short-window limit, the same request will work again shortly.

429 — "This MCP server's per-client request limit was reached"

This one comes from the connector, not Raken. It caps how many requests a single connection can make in a short rolling window — a safeguard against runaway or concurrent bursts. You'll recognize it by the wording ("this MCP server's per-client request limit") and it tells you roughly how many seconds to wait.

Unlike either Raken 429 above, there's no daily quota and nothing plan-related — it clears on its own after a short wait.

What to do:

• Wait the few seconds the message indicates, then retry.
• Avoid firing many tool calls at once — this usually happens when an AI assistant fans out calls concurrently (e.g. paging a large list as fast as possible). Ask it to go one step at a time. The connector already instructs the AI assistant to do this by default, but that's guidance rather than a hard stop — it can still be ignored, so it's worth saying explicitly when you're working through many records.

500 / 502 / 503 / 504 — "Raken is temporarily unavailable"

Any 5xx status means the problem is on Raken's side — the service may be undergoing maintenance or hitting a transient outage, not anything wrong with your account, your sign-in, or your request.

What to do: wait a few minutes and try again. These are usually brief. If it persists, check Raken's status channels or contact Raken support.

Still stuck?

• Re-run the smoke test from the setup guide ("Who am I in Raken?" → get_user_info) to isolate whether the problem is the connection itself or a specific tool / account permission.
• Disconnect and reconnect the connector from your AI assistant's connector settings (in Claude, Settings → Connectors) to re-run the OAuth sign-in.
• Contact Raken support: support@rakenapp.com.