# Error codes

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

Kind: reference · ~4 min · Verified v0.66.1 · Next: [What's new](https://pr-764-stg.superartifacts.app/docs/reference/whats-new.md)

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](https://pr-764-stg.superartifacts.app/docs/reference/plans.md). |
| `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_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](https://pr-764-stg.superartifacts.app/docs/concepts/artifacts.md). |
| `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](https://pr-764-stg.superartifacts.app/docs/reference/plans.md). |
| `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](https://pr-764-stg.superartifacts.app/docs/reference/limits.md). |
| `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. |