Errors and troubleshooting

What goes wrong when using Happierleads through an AI assistant, and how the assistant and you recover.

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

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) 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 come back as a message the assistant can read, marked as an error:

{ "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

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).