Error codes

HTTP answers { "error": { "code", "message" } }; MCP answers { "ok": false, "code", "message" }. Branch on code, show message. MCP in the status column means the code arrives in a tool result rather than an HTTP status. Every message says what went wrong and what to change.

Code	Status	What to do
ambiguous_dataset	400	Several artifacts carry that dataset; name one from the message.
artifact_changed	409	The owner changed the artifact mid-edit. Nothing was saved; read it and retry.
body_too_large	413	Operator endpoint; send no body.
browser_request_refused	403	The API is for agents and scripts; call it without Origin headers.
bundle_too_large	413	The bundle is over 10 MiB. Remove or shrink files.
capability_expired	401	The page was open too long or its access changed. Reload it.
claim_expired	410	The guest page expired and was deleted.
claim_taken	409	The guest page was already claimed.
claim_unknown	404	The claim link was not issued by this plane.
companion_slug_taken	409	A template part's slug is already one of your other artifacts. Pick another slug.
duplicate_slug	400	Two instances share a slug. Give each its own.
editors_unavailable	403	Naming an Editor needs a paid plan (Solo or above). Name them a Commenter or Viewer, or change plan.
erasure_failed	502, 503	Nothing was deleted. Retry.
external_sharing_blocked	403	The workspace's admin policy forbids sharing outside it.
field_not_groupable	400	Group by a closed-choice field with pii: none.
field_not_queryable	400	Sensitive fields cannot be filtered; filter a coarse companion field.
file_too_large	413	One file is over 5 MiB.
forbidden	403	Signed in, but this is not yours to do. Do not retry.
gone	—	Declared, not returned by any route today.
guest_attempts	429	Too many anonymous publish attempts from this address today. Wait, or connect an account.
guest_capacity	429	Anonymous publishing hit its daily ceiling. Wait, or connect an account.
guest_policy_refused	422	The guest page's policy was refused; the message says why.
guest_quota	429	This address published its anonymous pages for today. Wait, or connect an account.
guest_unavailable	503	Anonymous publishing is down. Retry shortly.
handle_taken	409	Operator rename onto a handle in use.
hash_mismatch	400	A file's bytes do not match its sha256. Re-encode and resend.
index_unavailable	503	Operator endpoint; the plane is missing its ingest secret.
internal	500, 502	Something failed on our side. Retry; if it persists, report it.
invalid_acting_for	400	actingFor needs creatorId, email and handle.
invalid_analytics	400	analytics is true or false.
invalid_arguments	MCP	The tool's arguments are wrong; follow fix and accepts.
invalid_base64	400	A file's content is not valid base64.
invalid_collection	400	collection is a string, or null to clear it.
invalid_comment	400	Send a JSON object such as {"body":"Fixed in v4."}.
invalid_creator	400	creatorId must be an account id.
invalid_cursor	400	Use the cursor the last page returned, with the same sort.
invalid_declaration	409	The new policy is not additive. Put back what the message lists.
invalid_description	400	description is a string, or null to clear it.
invalid_downloadable	400	downloadable is true or false.
invalid_email	400	Send an array of email addresses.
invalid_filter	400	Fix the filter clause: field, operator, value.
invalid_handle	400	A handle is required and must be valid.
invalid_header	400	header is true or false.
invalid_instances	400	Send instances, or a top-level slug and values, not both.
invalid_json	400	Send a JSON object.
invalid_key	400	A workspace key needs keyId and label.
invalid_key_hash	400	keyHash is the lowercase hex SHA-256 of the key.
invalid_kind	400	kind must be one of the seven artifact kinds.
invalid_live	400	live is true or false.
invalid_make_own	400	makeOwn is true or false.
invalid_members_can_edit	400	membersCanEdit is true or false.
invalid_move	400	Operator move with a malformed body.
invalid_path	400	Paths are relative, /-separated, under 256 characters, and never start with _.
invalid_policy	400, 413	The data policy failed a rule or a cap; the message names it.
invalid_query	400	The query was refused; edit it as the message suggests.
invalid_reason	MCP	A report's reason is too long. Say it in a sentence.
invalid_reassign	400	from and to must be two different accounts.
invalid_role	400, MCP	That role is not offered here. Use viewer, commenter or editor; collaborator and member still work as aliases. Admin was folded into Owner.
invalid_shot	400	Send the PNG bytes as the body.
invalid_showcase	400	showcase is true or false.
invalid_slug	400	Slugs are lowercase kebab, 3–63 characters.
invalid_social	400	social is {title, description, image}, or null.
invalid_spec	MCP	Send the template's whole spec when revising it.
invalid_template	400	The template slug names nothing. Look it up with super_templates.
invalid_title	400	title is a string, or null to clear it.
invalid_upload	400	Stage the file with super_upload and send its uploadId.
invalid_values	422	The values do not fit the template's slots; fix each listed problem.
invalid_version	400	version is a positive integer that exists.
invalid_visibility	400	visibility is private, organization or public.
invalid_window	400	since/until is an instant, a relative window or a version.
key_revoked	401, 409	The key was revoked. Reconnect.
length_required	411	Send a Content-Length.
live_invalid_message	WebSocket	Send JSON frames.
live_unknown_message	WebSocket	Send ping, subscribe or, as the owner, phase.
manage_on_platform	403	Share or rename on the dashboard page the message names.
mcp_not_configured	500	This plane has no MCP backend. Use another plane, or HTTP.
mcp_timeout	504, MCP	No answer in 55 s; the call may still finish. Check before retrying a change.
mcp_unavailable	502	The MCP endpoint could not reach the worker. Retry shortly.
method_not_allowed	405	Use the method the message names.
missing_index	400	Add a non-empty index.html at the bundle root.
missing_prompt	400	Send metadata.prompt: one sentence on why this was built.
name_exhausted	409	Every -copy name is taken. Rename the duplicate.
no_files	400	Send a files array.
no_runtime	400	The template has no code to clone; write the page and super_publish it.
not_found	404	No such artifact, version, upload or route, or not yours to see.
order_mismatch	MCP	order must list every artifact in the project once.
organization_unavailable	403	Workspace-wide sharing needs a team workspace on Team.
page_refused	422	A guest page must be UTF-8 HTML.
partial_publish	MCP	Some pages of a batch published; the message lists which.
plan_limit	400, 402	Over a plan limit. Free space or change plan.
plan_required	402	Workspace keys need Team. Use a personal key meanwhile.
plan_unconfirmed	503	The workspace's plan could not be checked. Retry in a minute.
policy_field_conflict	409	A field changed type. Rename it and set replaces.
policy_with_template	400	Do not send policy, html or files with a template.
rate_limited	429	Too many calls; the message says when to come back. See Limits.
record_conflict	409	A concurrent write won. Retry.
reserved_slug	MCP	That slug is taken. Choose another.
role_unavailable	503	Your workspace role could not be confirmed. Retry.
scope_immutable	409	A key cannot change between personal and workspace scope.
shot_too_large	413	Crop the comment screenshot tighter, or post without one.
showcase_requires_public	400	Make the artifact public and published first.
slug_reserved	400	The platform reserves that slug. Pick another.
source_forbidden	403	A bound dashboard may only read an artifact you own.
source_not_found	400	The dashboard's source artifact does not exist.
source_shape_mismatch	400	Match the source stream's declared shape.
source_stream_unknown	400	The source declares no stream by that name.
source_visibility_forbidden	400	A public dashboard may not read rows; use aggregate or count.
template_exists	MCP	You already own that template; revise it instead.
templates_unavailable	503	The template registry is unreachable. Retry shortly.
too_many	MCP	Too many entries or addresses in one call. Split the batch.
too_many_files	400	More than 200 files.
too_many_instances	400	Too many instances in one template publish. Split the batch.
too_many_slugs	400	Too many slugs in one listing. Split the request.
unauthorized	401	No key, a wrong key, or a key from another plane (production or staging). Ask your agent which account it uses.
unknown_dataset	400	No dataset has that key.
unknown_tool	MCP	No tool by that name; accepts lists the current ones.
upload_incomplete	400	PUT every declared file, then publish again.
version_published	409	Publish another version before deleting this one.
workspace_deleted	401	The workspace was deleted. Its owner can restore it within 30 days.