> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt > Use this file to discover all available pages before exploring further. # Gateway runbook > What each failure means, who fixes it, and what to check first — for staff running Hiveku accounts through the gateway ## 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. **Settings → Built-in tool policy**, looking for an entry set to *Blocked* — including any arriving from org-managed settings. 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](mailto:support@hiveku.com)**. This is not yours to fix. ### "This key has spent $… 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](mailto: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](mailto: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 ``` *.hiveku.com ``` 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. ### Tools → Enable tool search 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: ```bash theme={null} NODE_USE_ENV_PROXY=1 node your-script.mjs ``` The plugin's own MCP bridge handles this for itself from **0.9.2**. ## Checking spend yourself ```bash theme={null} curl -s -H "authorization: Bearer $YOUR_GATEWAY_KEY" \ https://gateway.hiveku.com/usage ``` 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: | Model | A heavy session | 20 staff, daily | | ------------- | --------------- | --------------- | | GLM-5.3 (max) | \~\$3.50 | \~\$1,550/month | | Kimi K3 (max) | \~\$8.40 | \~\$3,700/month | | GLM-5.3-Flash | \~\$0.38 | \~\$170/month | **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: ```bash theme={null} node ~/.claude/plugins/marketplaces/hiveku/scripts/sweep-tools.mjs ``` 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](mailto: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.