Skip to main content
Every failure below is a real, deliberate response from the platform — not a bug to work around. Each one names the fix.

“The PracticeHub API is not available on this account.”

Where it shows up: trying to connect at all — the MCP URL, the OAuth consent screen, even /.well-known/oauth-authorization-server — all return 404 with code: "not_available" before anything about the account is checked.Cause: the AI connector platform is a PracticeHub 2.0 feature that’s switched on account by account. This account either isn’t on PracticeHub 2.0 yet, or is on 2.0 but hasn’t been given the platform. This is checked before authentication, so it looks identical to an unknown clinic — nothing about your account leaks from the response.Fix: this isn’t a role-permission problem, so changing anyone’s permissions won’t help. Ask PracticeHub to enable the API platform for your account (Developers → API Keys will show “Request access” if that’s the situation you’re in).
Where it shows up: the connection worked, the assistant is doing things — then one particular action (a read or a write) comes back as a tool error instead of a result.Cause: the connector acts with the team member’s own role permissions, and this action needs one this role doesn’t have. The message names it, e.g. “Your role does not allow you to write patient_logs (requires edit_patient).” Related, narrower messages you’ll see for the same reason:
  • “Your role has read-only calendar access.” — booking or moving an appointment, with a role that can view the calendar but not edit it.
  • “Your role is limited to your own calendar.” — trying to book or move an appointment into a colleague’s diary from an own-calendar role.
  • “Your role is limited to your own patients; new patients must be added in PracticeHub.” — an own-patients role trying to create a brand-new patient (which would have no default practitioner, so it’d be invisible to them the moment it saved).
  • “This patient is outside your own-patients scope.” — an own-patients role trying to write something (a note, an invoice line, an appointment) against a patient who isn’t theirs.
Fix: this is the practice’s own rule working as intended, not a bug. If the team member should be able to do this, an account owner grants the named permission to their role (Settings → Security → Roles); if not, the refusal is correct and no change is needed. A good assistant will just relay the message rather than retry.
Where it shows up: a call that used to succeed suddenly gets 401 with code: "unauthenticated".Cause and fix depend on how long it’s been:
  • A one-off, then it works again on retry — expected. Access tokens last one hour; a well-behaved AI app refreshes silently in the background using its refresh token, and the person using it shouldn’t even notice. Nothing to do.
  • Persistent, doesn’t recover on its own — the refresh token itself has expired (30 days with no use at all — a connector nobody’s touched for a month) or was revoked (someone used Connected AI apps to cut it off, or the app was removed from the AI app’s own settings). The team member needs to go through the connect flow again from their AI app; see Connectors.
  • Comes back as code: "user_inactive" instead (“This user account is no longer active.”) — the team member’s PracticeHub account itself is deactivated, not just the connector. Reactivate the account, or connect as someone else.
Where it shows up: a lookup that should obviously find someone comes back empty, with no error at all.Cause: this is almost always the own-patients ringfence, not a bug or a permission refusal. A role limited to own patients has every patient outside “default practitioner = me” quietly filtered out of results — it isn’t told “no” the way a write is, the patient just isn’t there to find, exactly as if it didn’t exist to that role.Fix: check who the patient’s default practitioner is. If it should be visible more broadly, an account owner switches that role from “Access ONLY OWN patient files” to “Access ALL patient files” (Settings → Security → Roles → Patient Access), or the lookup is done by/through someone who is that patient’s default practitioner.
Where it shows up: code: "rate_limited", "Too many requests."Cause: MCP calls are capped at 120 requests a minute per account, shared by every connector on it (REST API keys have their own separate 120/minute budget, so a batch job elsewhere isn’t the cause). A normal conversation rarely hits it on its own; a runaway loop (an agent stuck re-querying the same thing), or several assistants working the account at once, can. Registering a new connector is capped separately at 10 registration attempts a minute per account — but that only affects the initial “add connector” step, not normal tool use afterwards.Fix: for a conversational assistant, this usually means it’s looping — stop it and start again, ideally with a more specific request. If several team members’ assistants are working the account at once, they share the same allowance; the limit resets every minute.
All of the above are visible after the fact too: Developers → API Logs shows every call with its status and error code, attributed to the credential that made it — the fastest way to confirm which of these you actually hit.