Skip to main content

​
Read this first

Most failures on the gateway are not what their message says. The client reports several unrelated conditions as authentication problems, so “sign in again” is rarely the fix. Find your symptom below. Each one says what it actually is, whether it is yours to fix, and what to check.

​
Symptoms

​
”Failed to authenticate. API Error: Blocked”

Not an authentication problem. Blocked is a value in the desktop app’s Built-in tool policy, and the client reports any local refusal as an auth failure. The tell is timing: the error appears in milliseconds with no tokens used, because no request was ever sent.
1

Check the tool policy

Settings → Built-in tool policy, looking for an entry set to Blocked — including any arriving from org-managed settings.
2

If nothing is set, start a new conversation

The condition is session-local. Signing in again will not clear it.

​
”Rate limited · Retrying (4/10)” that never succeeds

The provider account has run out of balance. Both upstreams report an empty balance with the same status code as a rate limit, so the client retries something retrying cannot fix. Gateway builds from 2026-08-28 return a clear billing error instead. Switch models in the picker to keep working, and email support@hiveku.com. This is not yours to fix.

​
”This key has spent …today"/"Hiveku′sgatewayhasspent… today" / "Hiveku's gateway has spent … across all keys”

A spend ceiling. The message says which one.
  • Your key — $25/day by default. Check what you have been running.
  • All keys — the whole team’s daily total. Not about you; someone else’s work reached it, or several people’s together.
Both clear at UTC midnight. Email support@hiveku.com if the work genuinely needs more.

​
”Prompt is too long” / context full

Every message carries the whole conversation, so a long session eventually fills even a 1M window. Compact the chat, or start a new one. If it happens within a few turns, the cause is the tool catalogue rather than your conversation — make sure the Hiveku plugin is 0.8.0 or later, which advertises a handful of tools instead of ~1,500 and keeps the rest searchable. Check with /hiveku:status.

​
A shell command or script cannot reach Hiveku

Sandboxed sessions ship with a fixed egress allowlist that has no Hiveku entry. MCP tools still work, because that endpoint is permitted separately — which is what makes this confusing. Only shell-level access is denied. Add *.hiveku.com to the egress host settings. Entries are host or *.host, no scheme and no path.

​
Hiveku tools are missing entirely

The folder is not bound to an account. Run /hiveku:bind, or /hiveku:status to see what Claude thinks is going on.

​
A tool returns 401

That account’s key was revoked or rotated. Run /hiveku:connect to re-mint it.

​
Claude says a capability does not exist

Ask it to search: “search the Hiveku tools for …”. From 0.8.0 the plugin advertises a core set plus hiveku_find_tools, and everything else is found through that. Absence from the tool list is not absence from the product. If searching genuinely returns nothing, the tool may be newer than the plugin’s catalogue — tell support@hiveku.com which tool.

​
Settings that must be right

All under Configure third-party inference in the desktop app.

​
Workspace → General Restrictions → Allowed egress hosts

Sandboxed sessions ship with a fixed allowlist — npm, PyPI, GitHub, Ubuntu, crates, Playwright and Anthropic’s own hosts — and no Hiveku entry. MCP tools still work without this, because that endpoint is permitted separately, so the symptom is confusing: only shell-level access is denied. A script calling the API, or curl, gets deny network-outbound core.hiveku.com:443. *.hiveku.com covers core (the MCP bridge) and app (connect, key issuing, form webhooks). Entries are host or *.host — no scheme, no path.
Check whether that field extends the built-in defaults or replaces them. If the box is empty rather than pre-filled, paste the defaults back alongside your entry, or you will cut off package installs for every sandboxed session.
Turn it on — but know what it does not do.
This does not fix your context on the gateway. Claude Code treats any host other than api.anthropic.com as non-first-party and turns tool search off, and even when it is working it defers a tool’s schema, not its name and description. Measured with the toggle on: 447,400 tokens of tool definitions before the first message.Plugin 0.8.0 and later is what actually fixes it — the full catalogue lives on disk and a handful of tools are advertised. Update the plugin and start a new conversation.

​
Tools → Built-in tool policy

Leave this empty unless you have a specific reason. An entry set to Blocked produces Failed to authenticate. API Error: Blocked, which is not an authentication problem and cannot be fixed by signing in. Two further sharp edges:
  • An ask entry turns off “always allow” for that whole tool, so every call is confirmed individually.
  • In Code side chats, an ask entry on a file tool (Read, Write, Edit, Glob, Grep) blocks matching calls instead of prompting.
The plugin already pre-approves Hiveku’s read-only tools through its own hook, which is the safe half of what this setting is usually reached for.

​
Writing scripts inside a session

Node’s fetch ignores HTTPS_PROXY. Sandboxed sessions reach the network only through a proxy, so a Node script calling Hiveku fails while curl to the same host succeeds — which reads as “the API is down” when it is not.The flag must be set before Node starts; setting it inside the script does nothing:
The plugin’s own MCP bridge handles this for itself from 0.9.2.

​
Checking spend yourself

Returns tokens and dollars per key, today’s fleet total, and the last 25 failures with their reasons. This is actual spend at real provider rates — more accurate than the app’s own estimate, which prices at Anthropic list price and needs configuring before it shows anything at all.

​
Choosing a model

The three differ by roughly 20x in cost for the same work: GLM-5.3 is the default and the right choice for most work. Use Flash for mechanical volume — sweeps, list and report chains. Use Kimi when reasoning genuinely matters; it is capable and it is the expensive one. Most of the cost is re-reading context, not new input, which is why long agentic sessions favour the cheaper models more than the headline prices suggest.

​
What not to do

Do not ask Claude to call every tool to check they work. Around 1,500 tools means a permission decision and a transcript entry each, the transcript is re-sent on every later message, and the run fills the context and dies partway through having produced nothing.Use the sweep script, which does it in one process and writes a report:
It only calls tools the server declares read-only, so it cannot create, update, delete or send anything.
Do not leave Bypass permissions on. It accepts everything, including writes, deletes and sends. Use it for one focused task you are watching, then return to Auto.

​
Escalating

Email support@hiveku.com with:
  • which account folder you were in
  • the model shown at the bottom right
  • the exact error text
  • roughly when it happened
The gateway records every rejection with a reason, so a timestamp is usually enough to find it.
Gateway access is issued per person and is revocable. Never share a gwk_ key — usage and spend ceilings are attributed to the key, so a shared one makes both meaningless.