Errors and refusals

Every refusal a caller can meet, what each one means, and which ones are about you rather than about us.

Refusals come from two different places, and telling them apart is the whole trick to debugging quickly.

• The door. A request that never reached an action — no key, access switched off, too fast, no such action — answers a 4xx with an error object.
• The answer. A request that got through the door and reached the action answers 200, and the ok field says how it went. A declined action is still a 200 with "ok": false and a reason.

So branch on ok, not on the status code. If you would rather not read the body, the x-goosy-tool-error header carries true or false on every dispatched call.

Refused at the door

{ "error": { "code": "tenant_api.unauthenticated", "message": "…" } }

Status	Code	What it means	Who fixes it
401	tenant_api.unauthenticated	No usable key. Missing, mistyped, revoked and expired all answer identically — on purpose, so the endpoint cannot be used to find out which keys exist.	You — check the key, or create a new one
403	api_access.platform_disabled	Programmatic access is off across the whole platform. Nothing about your account or your key.	Us — contact support
403	api_access.account_disabled	Programmatic access is switched off for your account. Every key stops at once.	An account Owner or Admin
403	api_access.capability_denied	Your key is fine, but you do not hold Use the API and MCP.	An Owner or Admin, under Settings → Members & invites
403	tenant_mcp.surface_disabled	The API and MCP surface is not open for your account yet. Not your key, not your permissions.	Us
400	tenant_api.malformed_body	The body was not a JSON object. Send {} when an action takes no arguments.	You
400	tenant_mcp.batch_too_large	An assistant sent too many messages in one request. Send them one at a time.	Your client
404	tenant_api.unknown_tool	No action by that name. The answer deliberately names nothing, so it cannot be used to probe for actions.	You — check the spelling in the reference
429	tenant_mcp.rate_limited	Over this key’s per-minute cap. Wait for Retry-After.	You — see Rate limits

401 never tells you which credential problem you had. A revoked key, an expired one, a typo and a key that never existed all answer the same words. If you are unsure, look at the key’s row under Settings → API & MCP — it shows the status and when it was last used.

Refused by the action

These answer 200 with "ok": false, a code, and a plain-language message.

Code	What it means
workspace_ambiguous	Your key reaches several workspaces and nothing chose one. The reply lists them. See Choosing a workspace.
workspace_unreachable	The workspace you named is not one this key reaches — or the key is narrowed to a different one.
workspace_set_unsupported	You asked for a group of workspaces. Pass a single workspace instead.
invalid_arguments	The arguments did not match what the action takes. The reply lists which fields, so you rarely need the reference to fix it.
tool_capability_unbound	The action changes something, and the permission that would decide who may do that over the API does not exist yet — so it is closed to every key. Not about your credential or your role.
the action’s own codes	Anything specific to what you asked for — a board that is not there, an item that does not exist. The message says which.

An invalid_arguments reply points at the field:

{
  "ok": false,
  "code": "invalid_arguments",
  "message": "The arguments for \"library.get\" did not match its schema.",
  "issues": [
    { "path": "kind", "message": "Required" },
    { "path": "id", "message": "Required" }
  ]
}

Which refusals are about us

Four of the answers above are platform states. No new key, no permission change and no code change on your side will clear them, and each says so in its own message rather than leaving you to guess:

• tenant_mcp.surface_disabled — the surface is not open for your account yet.
• api_access.platform_disabled — programmatic access is off platform-wide.
• tool_capability_unbound — that action is not open to API clients yet.
• Anything a support reply tells you is on our side.

Everything else in this page has a fix you can perform.

A quick triage

1. Read the status first

   A 4xx means the request never reached the action. A 200 means it did.

2. On a 4xx, read the code

   The table above names who can clear each one. Most 403s are a switch or a permission, not the key.

3. On a 200, read ok

   "ok": true is a real answer. "ok": false carries a code and a message written to be acted on — including, where it applies, the list of choices you could pass instead.

4. If the message says it is not about your key, believe it

   Minting another key is the most common wasted step. The refusals that are not about your credential say so in those words.