Error codes

Every error code the serving plane and the MCP server return, its HTTP status, and what to do about it.

reference~4 minVerified v0.127.10

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.
`artifact_closed`	410	The artifact was deleted and can no longer hold storage.
`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.
`dataset_key_changed`	409	The artifact has responses under its dataset key. Keep the key; start a new log as a new artifact with `continues`.
`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 sharing 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_arguments`	400, MCP	The tool's arguments are wrong; follow `fix` and `accepts`. `super_data_schema {compare}` takes 2 to 10 artifacts you can read.
`invalid_acting_for`	400	`actingFor` needs `creatorId`, `email` and `handle`.
`invalid_analytics`	400	`analytics` is `true` or `false`.
`invalid_act_as`	400	`actAs` is for the platform's own credential; remove it.
`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. A template version you may not build from is refused at publish too.
`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_longer_builds`	403	You no longer build in the artifact's workspace, so this key cannot change it. Ask an owner.
`no_runtime`	400	The template has no code to clone; write the page and `super_publish` it.
`not_a_member`	403	You are no longer a member of the artifact's workspace, so this key cannot read it. Ask an owner.
`not_found`	404	No such artifact, version, upload or route, or not yours to see.
`not_series_bound`	400	The page reads no series. Declare `source: {series}` in its policy.
`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.
`permission_required`	409	A public or unlisted template from outside this workspace is not installed here. Ask the person, then install it with `confirmedByPerson: true`, then build.
`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.
`rollback_crosses_data_model`	409	That version collected a different data model. Roll back to one with the same model, or revise forward.
`scope_immutable`	409	A key cannot change between personal and workspace scope.
`series_changed`	409	The artifact has responses in its series. Keep the series; start a new one with new artifacts.
`series_check_unavailable`	503	The series could not be checked, so nothing was published. Retry shortly.
`series_measure_conflict`	409	A field's measure differs from the series. Use the series' measure, rename the field, or choose another series.
`series_rows_owner_only`	403	Rows across a series reach only the dashboard's owner. Read aggregates instead.
`series_too_large`	409	The series has more than 20 artifacts. Read it with your agent, or start a new series.
`series_type_conflict`	409	A field's type differs from the series. Use the series' type, rename the field, or choose another series.
`series_unit_conflict`	409	A field's unit differs in kind from the series, or one side has none. Use a unit of the same kind, rename the field, or choose another series.
`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`.
`stream_read_only`	403	Nothing writes to this stream or page. Write from the artifact that collects.
`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.
`workspace_suspended`	402	The company workspace is frozen or paused after its free period. Ask an owner to subscribe on Settings → Billing to restore writing. Existing content remains available to read or export.

From a page's own data calls

What an artifact's page meets when it saves or reads answers. The codes above that also apply here, such as rate_limited and not_found, are not repeated.

Code	Status	What to do
`already_submitted`	409	This visitor already answered: once per person, or once per value of `uniqueBy`. Offer to change the answer only if the policy uses `upsert`.
`append_only`	403	Answers here are final. To let people edit, publish with `writes: "upsert"`.
`artifact_closed`	410	The artifact was deleted. Stop.
`invalid_response`	422	A field failed its rule, or a required one was sent empty; the message names it.
`record_cap`	429	The artifact holds every answer its policy allows. Waiting does not help; tell the visitor.
`stream_closed`	409	The stream takes answers only in another phase. Wait for the host to open it.
`stream_required`	400	The artifact declares streams; name one with `?stream=`.
`unknown_stream`	400	No stream has that name; the message lists the ones declared.
`visitor_cap`	429	This visitor reached their own limit of records. Others can still answer.
`write_conflict`	409	Two saves of the same answers crossed. Nothing was stored; send it again.

When a live page is closed

A live page's connection ends with one of these codes, after a message that carries the reason. Reloading never loses a saved answer.

Code	Reason	What the page does
4401	`live_unauthorized`	Fetch a new token, once.
4403	`live_read_admin`	Nothing here is for visitors to hear. Stop.
4408	`live_idle`	Nothing was sent for 90 seconds. Reconnect, and ping every 30.
4409	`live_token_expired`	Reconnect at once with a new token.
4413	`live_payload_too_large`	A message over 32 KiB. Send less.
4429	`realtime_capacity`	The room holds 500 pages. Keep the token, wait and retry.
4430	`live_flooding`	Over 10 messages a second. Slow down.
4453	`live_room_closed`	The owner turned live off. Stop; reload later.
4454	`live_account_room_busy`	Another of the owner's artifacts holds the workspace's live room. Keep the token, say that live is paused and answers still save, and retry after `retryAfterMs` (20 seconds). See Live rooms.
4499	`live_room_expired`	The room has been open 8 hours. Reconnect.