# Errors and troubleshooting (/docs/mcp/errors)

There are two kinds of problem:

- **Connection problems:** the assistant can’t reach Happierleads at all. You fix these in your assistant’s settings.
- **Tool errors:** the connection works, but one call was refused. The error message goes back to the assistant, which reads it and usually corrects itself, for example by fetching a missing ID and trying again.

## Connection problems [#connection-problems]

| What you see | Why | Fix |
| --- | --- | --- |
| The assistant says it has no Happierleads tools | The connector isn’t added, or it’s switched off for this chat | Add it ([Quickstart](/docs/mcp#quickstart)) and enable it in the chat’s connector menu |
| “Unauthorized” or a request to sign in again | The key in the URL is wrong, or the OAuth session ended | Copy the connection URL again from **Integrations → MCP Server**, or reconnect to sign in |
| “Session not found or expired. Reconnect via /mcp/sse” | An older SSE connection dropped | Reconnect the connector; newer clients use Streamable HTTP and don’t hit this |
| It connects but tools time out | Your network blocks outside MCP servers | Ask your IT team to allow `rest-dash.happierleads.com` |

## Tool errors [#tool-errors]

Tool errors come back as a message the assistant can read, marked as an error:

```json
{ "error": "Tool not available for website-scoped key. Ask your account owner for a master key." }
```

| Message | Why | What the assistant should do |
| --- | --- | --- |
| “Tool not available for website-scoped key…” | A team member’s URL was used for an account-level tool | Tell you the account owner needs to do it, or connect with the owner’s URL |
| “websiteId is required…” / “…needs a prospectId (24 hex characters)” | It skipped a lookup step | Call `list_websites` (or the matching `list_` tool) for the ID, then retry |
| “Your plan does not allow the prospector” | The plan doesn’t include that feature | Stop and tell you; the fix is a plan change, not a retry |
| “You exceed the limits” | Too many calls in a short time, or a plan limit is used up | Wait before retrying; don’t loop |
| Payment required, with an upgrade link | The tool needs an add-on, e.g. `verify_contact` needs Email Waterfall | Show you the link; don’t retry |
| Empty results | Nothing matched | Suggest widening the filters, e.g. a bigger company size or more job titles |

## For assistant builders [#for-assistant-builders]

- Tool failures come back as tool results with `isError: true` and a JSON `error` message, not as protocol errors, so the model can read the reason and adjust.
- Treat plan, add-on and permission errors as final: retrying won’t change the answer.
- The server validates every input. The tool descriptions say which lookup tool provides each ID (`list_websites` → `websiteId`, `search_people` → `profileId`).