Refusals

When Slicemap refuses a call, your agent gets the reason in plain words with a code in brackets at the end, for example No story with that number in this workspace. (not_found). Most of the time the agent reads the message and fixes the call on its own. The table below is for when it can’t, or when you want to know what happened.

Problems with the key itself (the first six rows) are caught before any tool runs, so your agent usually reports that it can’t connect to Slicemap rather than a failed tool call.

Code	When	What to do
missing_token	The request carries no key.	Add the header Authorization: Bearer <your-api-key> to the Slicemap entry in your agent’s MCP config. See Connect your agent.
malformed_token	The key doesn’t look like a Slicemap key. Slicemap keys start with sm_pat_.	Check that you pasted the whole key and not something else.
revoked_token	The key is not valid any more: it was revoked, never existed, or its owner left or was removed from the workspace (the key goes away with the membership).	Create a new key in Settings > API Keys and put it in your agent’s config. Members ask an owner or admin for a key.
expired_token	The key has expired. The message gives the date.	Create a new key in Settings > API Keys. Members ask an owner or admin for a key.
not_a_member	A backup check: the key’s owner is no longer a member of the workspace. Usually the key is gone first and you get revoked_token.	Ask an owner or admin of the workspace to invite you again and to give you a new key.
lookup_failed	Slicemap couldn’t check the key or the workspace membership. The problem is on Slicemap’s side, not in the key.	Try again in a minute.
insufficient_permissions	The tool needs a right the key doesn’t carry: a “Read only” key called a tool that changes the map.	Create a key with “Read & write” access.
read_only_member	The tool changes the map, but the key owner’s role in the workspace is now Viewer, so the key can only read.	An owner or admin gives you back edit rights, and the same key writes again. See Roles and permissions.
write_limit	The key has already made 200 write calls within the hour, refused ones included.	Wait, or make the remaining changes on the board.
bad_request	The request body is not JSON shaped like {"tool": "<name>", "params": {...}}. Only direct HTTP calls can get this; calls through MCP can’t.	Fix the request body.
unknown_tool	No tool has that name. The message lists the tools that exist. Only direct HTTP calls can get this.	Use a name from the list or from Agent tools.
bad_params	A parameter is missing or wrong, and the message names it. Common cases: an estimate whose range doesn’t hold the expected minutes, clarity below 5 without saying what is missing, a release that would end before it starts, a step or chapter from another map, nothing to update, an assignee who can’t edit the map, or a stage order that doesn’t list every stage once. Over MCP, a missing parameter or one of the wrong type is caught earlier and comes back as “Input validation error” without a code.	Fix the parameter the message names and call again. For a stage order, read the stages again with slicemap_project_statuses.
not_found	Nothing with that id, number or name in the key’s workspace: a project, story map, step, story, criterion, release, stage, persona, chapter or note. It also comes when a project has no story map yet. A missing project gets a longer message: it names the key’s workspace and, when the project sits in another workspace of yours, where to create the right key.	Take ids from slicemap_board_snapshot and release names exactly as the board shows them. For a project in another workspace, create a key in that workspace.
duplicate_name	The name is taken: a release on this map, a stage or a persona in this project, or a project key another project of the workspace has or had.	Change the existing one, or pick another name.
estimate_frozen	The story has already been in work, or it sits in the done stage, so its plan is frozen and can’t be replaced.	Leave the plan as it is. See Agent estimates in minutes.
note_changed	The agent tried to change a note that someone changed after the agent read it: the updatedAt it sent is not the note’s current one. Nothing is written, so the other person’s text is safe.	Read the note again with slicemap_get_note, keep what the other person wrote, and send the change on top with the new updatedAt.
criteria_unchecked	The agent tried to move a story to a stage marked Closed while some acceptance criteria are unchecked. The message lists them.	Check each criterion as you verify it with slicemap_toggle_ac_done, then move the story again. See Write acceptance criteria your agent can check.
not_allowed	The key owner’s role doesn’t allow this, the same as in the app. A stage, a map or a project is deleted only by an owner or admin; members, invite links, keys and the workspace are managed only by an owner or admin; the workspace is deleted only by its owner.	Ask an owner or admin to do it or to change your role. See Roles and permissions.
last_owner	The change would leave the workspace without an owner: the only owner can be neither removed nor demoted, and can’t leave.	Make someone else an owner first.
last_workspace	The agent tried to delete its owner’s only workspace. Without one the app has nowhere to take them after sign-in.	Create or join another workspace first.
last_view	The agent tried to delete a map’s last tab. A map keeps at least one.	Add another tab first, or keep this one.
stage_has_code	The stage carries a service code (todo, ready-for-dev, in-progress, done) that agents find it by, so it can’t be deleted.	Rename the stage instead.
needs_new_default	The agent tried to delete the project’s default stage without naming the stage that takes its place.	Call again with newDefaultStatusId.
key_taken	A project can’t come back from the trash: another project of the workspace has its key now.	Change that project’s key, then restore again.
place_gone	What the item lay in is deleted: a story’s step, a step’s map, a stage’s project. The message names it when it is in the trash too.	Restore the item the message names first. If it is deleted for good, there is nowhere to put the item back.
place_taken	An item can’t come back from the trash because its name or address is taken: a release with the same name on the map, a persona or a stage in the project, a project with the same address.	Rename the one that took its place, then restore again.
write_failed	The change didn’t go through, and the message carries the reason. Sometimes part of it did: a release, step or stage was created but couldn’t be put in place, or a new release couldn’t be made active. The message then says so.	When the message names what was created, finish with the tool it names, or on the board. Otherwise read the current state before trying again.
read_failed	Slicemap couldn’t read something it checks before answering. The problem is on Slicemap’s side.	Try again later.
tool_failed	The tool failed for a reason it didn’t expect.	Try again later.

Caution

Before you repeat a slicemap_record_work call that failed without a clear answer, read the story with slicemap_get_story. A second call adds the minutes twice.