Webpath Error Types

Every Webpath error is RFC 7807 application/problem+json. Its type is a stable URI under https://muse.as/a/webpath/errors/ that resolves to a page like the ones linked below — title, the HTTP status, what it means, and how to recover. The response's own detail field is always a full sentence you can relay to a user as-is.

{
  "type": "https://muse.as/a/webpath/errors/etag-mismatch",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The file changed since you last read it. Re-read it and retry your write."
}

73 error types, grouped by area.

Identity

Type	Status	Meaning
`access-required`	403	This host gates entry behind Cloudflare Access and you have not passed it.
`auth-required`	401	The operation needs a signed-in account or a key, and none was presented.
`idp-only`	403	This host only accepts sign-in through its configured identity provider.
`otp-expired`	401	The one-time code has expired, or no code is currently active.
`otp-invalid`	401	The one-time code did not match.
`otp-rate-limited`	429	Too many sign-in codes have been requested for this email or IP.
`passkey-challenge`	400	The passkey registration or sign-in challenge timed out.
`passkey-invalid`	400 / 401	The passkey assertion could not be verified, or no matching account was found.
`passkey-not-found`	404	No passkey with that id exists on this account.
`passkey-unknown`	401	The presented passkey is not registered to any account.
`untrusted-target`	400	This host cannot carry your sign-in to the space you asked for.

Keys

Type	Status	Meaning
`format-not-allowed`	403	The key's formats allowlist excludes this file type.
`out-of-scope`	403	The key is being used outside the space, path, or operations it is scoped to.
`scope-invalid`	422	The requested key scope is missing a namespace or is otherwise invalid.
`token-conflict`	400	A header key and a query key were both sent and disagree.
`token-expired`	401	The key has passed its expiry time.
`token-invalid`	401	The key is not in a recognizable form.
`token-missing`	401	This operation needs a key and none was sent.
`token-not-found`	404	No key with that id exists on your account.
`token-revoked`	401	The key was revoked — individually, or by a space-wide key reset.

Spaces

Type	Status	Meaning
`bad-host`	400	The Host header was missing or is not a Webpath host.
`bad-name`	422	The supplied name is invalid.
`host-not-open`	403	This host does not let the public join new spaces.
`no-space`	401	The space this key was minted for has been deleted.
`space-free`	404	No one has joined this name yet.
`space-is-platform-host`	409	This hostname is a platform host, not a joinable space.
`space-name-invalid`	422	The name breaks the naming rules.
`space-name-reserved`	422	The name is a reserved label this host keeps for itself.
`space-name-taken`	409	That space name has already been joined.
`space-not-found`	404	No space exists at this host.

Files

Type	Status	Meaning
`already-exists`	412	If-None-Match: * was set, but a file already exists at this path.
`append-conflict`	409	Concurrent appends kept colliding under the retry limit.
`bad-patch`	422	The ?replace patch batch is malformed.
`bad-path`	400	The path is malformed or attempts directory traversal.
`etag-mismatch`	412	An If-Match precondition failed: the file changed (or does not exist).
`file-type-not-allowed`	415	The host or space upload policy forbids this file extension.
`internal`	500	The server hit an unexpected error completing the request.
`invalid-append-body`	400	The body is not valid for a line-oriented file (bad JSON line, unterminated field, or non-UTF-8).
`method-not-allowed`	405	This path does not support that HTTP method.
`not-appendable`	409	This type's syntax spans the whole file (JSON, HTML, XML, YAML…) or it is binary, so concatenation would corrupt it.
`not-found`	404	Nothing readable lives at this path — it may not exist, or it may be private.
`not-html`	415	?replace edits only HTML files, and this is not one.
`patch-conflict`	409	Some ?replace fragments no longer match the stored page.
`precondition-required`	428	This write must carry an If-Match precondition and none was sent.
`range-not-satisfiable`	416	The requested byte range lies outside the file.
`too-large`	413	The body, or the combined result, exceeds the size cap.

Metadata

Type	Status	Meaning
`bad-description`	422	The description is invalid or over the 500-character limit.
`bad-layer`	422	The layer value contains unrecognized tokens.
`bad-sharing`	422	The sharing map is malformed.
`bad-tags`	422	The tags value is malformed.
`bad-visibility`	422	The visibility value is not one of the allowed levels.
`field-not-writable`	422	A field in the PATCH is server-owned, or not allowed on this target.

Reserved

Type	Status	Meaning
`audit-read-only`	405	The audit log is read-only.
`bad-browse`	422	The browse settings are invalid.
`bad-uploads`	422	The uploads policy value is invalid.
`config-read-only`	405	_config.json is a projection — PUT is not allowed.
`links-read-only`	405	_links.json is derived and cannot be written.
`llms-generated`	405	llms.txt is synthesized fresh on every read and cannot be written.
`search-all-platform-only`	403	Reindexing every space may only run on a platform host, by its owner.
`search-read-only`	405	_search is a control surface, not a writable file.
`stats-generated`	405	Visitor stats are synthesized and read-only.

Query

Type	Status	Meaning
`bad-og`	400	The ?og form is not recognized.
`bad-qr`	400	The ?qr form is not recognized.
`bad-request`	400 / 422	The request was malformed for this endpoint — bad JSON, a missing field, conflicting flags, or nothing to change.
`bad-search`	400	The search query was empty.
`confirm-required`	400	Deleting a whole space or prefix needs an explicit confirmation.

Sharing

Type	Status	Meaning
`admin-not-delegable`	403	An admin grant cannot itself re-grant admin.
`bad-access-rule`	422	A drop-box _access.json rule is malformed.
`drop-exists`	409	A drop box is create-only and that name already exists.
`drop-is-private`	403	A drop-box write tried to set a non-private visibility.
`grant-does-not-cover`	403	Your grant does not extend to this path or operation.
`grant-is-content-only`	403	Your grant lets you edit content, not visibility.
`sharing-owner-only`	403	Only the owner, or a whole-space write key, may change sharing.

→ Spec · API Reference · Conformance · Webpath home