When a call is refused
A refusal always happens before the provider or vendor is reached. It is JSON with an error code, and the x-flocktab-reason header names the rule. The same table is in the terminal: tab help errors.
| HTTP | error | When | What to do |
|---|---|---|---|
| 402 | tab_closed | The tab is closed, or not even a short answer fits what is left on it (the message says how much is left). | tab open, raise the cap with tab cap, or wait for the window to roll over. |
| 402 | tool_cap | A per-tool cap is reached. | Raise that tool's cap in the console. |
| 403 | risk_blocked | An irreversible tool that the Agent's policy does not allow, or less than $25.00 of the cap remains. | tab policy --allow <tool>, and leave room under the cap. |
| 403 | model_blocked | The model is not on the Agent's allowlist. | tab policy --models ..., or none to allow any. |
| 403 | agent_frozen | Reserved: not sent by the hosted ledger today. | If you see it, write to support. |
| 403 | not_metered | An API-key Agent's own key sent a write the tab cannot meter (batches, embeddings, legacy completions, a path spelled another way) through /t/. | Use the model endpoints (chat completions, responses, messages); anything else runs outside the tab. |
| 403 | not_subscription | A passthrough (/t/...) call for an API-key Agent. | tab agent kind <agent> subscription, or run it metered. |
| 403 | wrong_harness | A passthrough for another harness than the Agent's: a Claude Agent's key with a Codex login, or an untied Agent with any login. | Run tab <harness> in the folder and pick or make that harness's Agent; or tab agent harness <agent> <harness>. |
| 429 | velocity | More calls this minute than the policy allows. | Wait, or tab policy --velocity N. |
| 401 | key_revoked | The key is unknown, rotated or missing. | tab key rotate mints a fresh one on this machine. |
| 503 | ledger_unavailable | FlockTab could not reach its ledger. Nothing was sent to the provider. | Retry. This is fail closed on purpose. |
Common problems
Start with tab status
It says whether this machine is logged in, which Agent this folder runs as and its kind, and whether the proxy answers. Most problems are one of those three. tab log -f then shows each call as it lands, with the reason when one is refused.
Claude Code asks “Detected a custom API key… use this key?”
That key is the tab's, from a tab older than 0.1.9 on an API-key Agent, or from an old self-hosted proxy that did not report the Agent's kind. Answer No, then tab update (and on self-hosted, tab down && tab up with nothing running). Current versions hand Claude Code the key in a way it never asks about, and a Subscription Agent gets no key at all.
401 “Blocked: missing API key” in Claude Code
The folder runs as an API-key Agent but Claude Code used its own Claude login, so the call arrived without the tab's key. Either the Agent should be a Subscription one (tab agent kind <agent> subscription), or update tab so the key is passed as an auth token.
“The local proxy is older than this tab”
tab was updated while the self-hosted proxy kept running the old binary. It still works, but newer features are missing. When no agent is running through it: tab down && tab up. tab never restarts it for you, because that would cut whatever is streaming.
Codex: “No saved session found with ID …”
From an older tab, whose Codex home could not see the conversations in ~/.codex. Update; the first tab codex after that links them, and moves across anything recorded under tab in the meantime.
A pool login shows “no call through FlockTab yet”
Usage is only known once that login has made a call through FlockTab. Until then it counts as unused and is picked first. Run one call as it (tab claude --as <login>) and its windows appear.
tab pool add kimi: “No login found”
From an older tab, which pointed the newer Kimi Code at the wrong home variable, so it signed in to your normal Kimi login instead of the pool folder. Update and run the same command again.
A hosted call fails with no unlock
The saved provider key can only be opened with your unlock, and FlockTab does not have it. tab login asks for it and checks it; without tab, send it inside the key after a dot or as x-flocktab-unlock.
Spend shows $0.00 on a Subscription Agent
Correct: nothing is charged. Its card and page show what it used of your plans at list price, and its share of subscription usage on the same harness (Claude, Codex, Grok or Kimi). This is not the provider’s quota. The overview's money totals count metered tabs only.
Asking for help
Send what these print. None of it contains a key, a login or a prompt.
tab version
tab status
tab log --lines 20
tab log --proxy # self-hosted only