Errors and refusals

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.
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.

Both carry the same fields — ok: false, a code and a message at the top level — so one branch in your code reads either. 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. Every response also carries an x-request-id; quote it when you contact support. More in API conventions.

Refused at the door

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

The nested error object repeats the same values and is deprecated — read the top-level fields.

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
`400`	`tenant_api.idempotency_key_invalid`	The `Idempotency-Key` header was empty, too long, or had spaces or other characters that are not allowed.	You
`400`	`tenant_api.idempotency_key_conflict`	The `Idempotency-Key` header and the `idempotency_key` field disagreed. Send one key, in the header.	You
`400`	`tenant_api.idempotency_unsupported`	This action cannot replay a retry yet, so it takes no `Idempotency-Key`. Check whether the first call landed before retrying.	You
`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

Read the status first

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

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.

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.

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.

Get started

API guides

Connect an assistant

API reference

Refused at the door

Refused by the action

Which refusals are about us

A quick triage

​Refused at the door

​Refused by the action

​Which refusals are about us

​A quick triage

Refused at the door

Refused by the action

Which refusals are about us

A quick triage