Problems

Wispist API errors use RFC 9457 Problem Details and application/problem+json:

{
  "type": "https://learn.peios.org/wispist/problems/revision-conflict/",
  "title": "Revision conflict",
  "status": 412,
  "detail": "The document changed after it was read.",
  "instance": "urn:uuid:019c0000-0000-7000-8000-000000000000"
}

The type URI is the primary machine identifier. It is permanent even if the implementation or documentation later moves. title is stable for that type; detail describes this occurrence. status matches the HTTP status.

instance is a urn:uuid: URI built from the same UUID returned in X-Request-ID. Give that request ID to an operator when investigating a server-side failure.

Validation problems may add an errors array of JSON Pointer and detail objects. Internal SQL, paths, stack traces, document bodies, tokens, and policy predicates are never returned.

The browser client maps known type URIs to convenient error.code values:

HTTP headers retain their normal authority. Retry-After, ETag, Allow, and WWW-Authenticate are not replaced by Problem Details members.

Canonical type:

https://learn.peios.org/wispist/problems/invalid-request/

Status: 400 Bad Request. Browser code: invalid_request.

Wispist returns this problem when the request cannot be interpreted under the v1 resource contract. Examples include an unknown or repeated query parameter, invalid collection or document ID, non-canonical path, malformed cursor, unknown request-envelope member, or contradictory conditional headers.

This differs from Invalid JSON: the JSON may be syntactically valid while its protocol envelope or request metadata is not.

Correct the request rather than retrying it unchanged. Use the browser client where possible; it constructs canonical paths, envelopes, pagination, and mutation preconditions.

Canonical type:

https://learn.peios.org/wispist/problems/invalid-json/

Status: 400 Bad Request. Browser code: invalid_json.

The submitted document representation is not permitted JSON. Wispist rejects malformed or invalid UTF-8 input, a data root that is not an object, duplicate object member names, more than 32 nesting levels, keys longer than 256 UTF-8 bytes, and trailing JSON values.

Generate the body with a normal JSON serialiser and pass a non-null object to the browser client. Duplicate members must be fixed at the producer; Wispist does not choose which ambiguous value wins.

An oversized representation uses Request too large instead.

Canonical type:

https://learn.peios.org/wispist/problems/authentication-required/

Status: 401 Unauthorized. Browser code: authentication_required.

The collection operation is declared authenticated, but the host did not bind an authenticated principal. The response includes WWW-Authenticate.

Wispdeck's initial hosted-site integration supplies anonymous principals to public and preview JavaScript. A dashboard session or private preview cookie does not automatically become Wispist identity. Until a host identity integration is configured, change the operation to anyone only if public access is genuinely intended, or leave it inaccessible.

An authenticated principal that still lacks permission receives Forbidden.

Canonical type:

https://learn.peios.org/wispist/problems/forbidden/

Status: 403 Forbidden. Browser code: forbidden.

The bound principal may not perform the operation. Common causes are:

• The collection operation is nobody.
• A mutation did not carry the exact bound site Origin, or Fetch Metadata identified it as cross-site.
• The request is using Wispdeck's Current preview, whose live-data binding is unconditionally read-only.
• A configured authoriser denied the current or proposed document.

Do not retry unchanged. Check wispist.readOnly to adjust Current-preview UI, and compare the active release's wispist.json with the operation being attempted. Client metadata is only a UI hint; the server remains authoritative.

Canonical type:

https://learn.peios.org/wispist/problems/not-found/

Status: 404 Not Found. Browser code: not_found.

The requested resource is unavailable. A document may not exist, the active release may not declare the collection, or the path may not identify a v1 resource.

Wispist does not reveal hidden stored documents merely because an older release once declared them. Removing a declaration makes the collection unavailable without deleting its data.

For get, treat this as an absent document where that is valid application state. For an entire collection, inspect the declaration attached to the release serving this request.

Canonical type:

https://learn.peios.org/wispist/problems/method-not-allowed/

Status: 405 Method Not Allowed. Browser code: method_not_allowed.

The path names a known Wispist resource, but its method is not supported. The Allow response header lists valid methods and is authoritative.

For example, a collection document resource supports GET, HEAD, PUT, and DELETE, while the change stream supports only GET. Use the route table in the HTTP API reference or the browser client.

Canonical type:

https://learn.peios.org/wispist/problems/idempotency-conflict/

Status: 409 Conflict. Browser code: idempotency_conflict.

The Idempotency-Key was already used in this namespace for a different generated-ID POST. Wispist retains each successful key and response for at least 24 hours so a lost response can be retried safely.

If this is a retry, send exactly the same method, path, and document data. If it is a new logical create, generate a new strong random key. The built-in collection.add method does this automatically.

This problem concerns POST request identity. Concurrent document revisions use Revision conflict.

Canonical type:

https://learn.peios.org/wispist/problems/quota-exceeded/

Status: 409 Conflict. Browser code: quota_exceeded.

The mutation is valid in isolation but would exceed a storage bound. The transactional check may cover collection document count, total live or draft document bytes, or the maximum number of unexpired idempotency records.

Delete data that is no longer needed, reduce the proposed document, or ask the operator to review installation policy. A release declaration may lower limits but cannot raise them.

A single request or document that exceeds its byte limit uses Request too large.

Canonical type:

https://learn.peios.org/wispist/problems/revision-conflict/

Status: 412 Precondition Failed. Browser code: revision_conflict.

The mutation's HTTP precondition did not match current state:

• If-None-Match: * was used to create an ID that already exists.
• If-Match carried an older revision for replacement or deletion.

Fetch or wait for the latest document, reconcile the user's intent, then submit a new conditional mutation using that revision. Never loop blindly: another caller may have made a meaningful conflicting change.

The browser client's replace, update, and delete methods accept an observed document envelope so safe concurrency is the normal path.

Canonical type:

https://learn.peios.org/wispist/problems/request-too-large/

Status: 413 Content Too Large. Browser code: request_too_large.

The request body or data representation exceeds the active collection limit. Wispist limits the body before decoding and allows only a small fixed amount beyond the document limit for the JSON envelope.

Reduce the document or split independent records into separate documents. A release may request a higher collection limit only up to the operator's host maximum.

Total namespace storage exhaustion uses Quota exceeded.

Canonical type:

https://learn.peios.org/wispist/problems/unsupported-media-type/

Status: 415 Unsupported Media Type. Browser code: unsupported_media_type.

Document create and replacement bodies require:

Content-Type: application/json

Media-type parameters such as charset=utf-8 are accepted, but another base type or a missing header is not. Set the header and send the documented {"data": {...}} envelope.

JSON that has the correct media type but invalid content uses Invalid JSON or Invalid request.

Canonical type:

https://learn.peios.org/wispist/problems/precondition-required/

Status: 428 Precondition Required. Browser code: precondition_required.

Wispist does not offer unconditional last-write-wins mutation. A selected-ID create requires If-None-Match: *. Replacing or deleting an existing document requires If-Match with the quoted observed revision.

Read the current document and use replace, update, or delete with that complete envelope. If the supplied revision is no longer current, the next response is Revision conflict.

Canonical type:

https://learn.peios.org/wispist/problems/rate-limited/

Status: 429 Too Many Requests. Browser code: rate_limited.

A read, mutation, generated-ID create, installation-wide request, or concurrent change stream exceeded its bounded allowance. Retry-After gives the minimum server-selected delay in seconds.

Wait for that delay and retry with backoff. Avoid tight loops, duplicate subscriptions, and unnecessary full-list refreshes. The built-in subscription client already reconnects with bounded exponential backoff.

Rate limiting is an availability control. It does not change collection policy or make public writes private.

Canonical type:

https://learn.peios.org/wispist/problems/temporarily-unavailable/

Status: 503 Service Unavailable. Browser code: temporarily_unavailable.

Wispist could not safely complete the operation. Expected transient causes include a busy SQLite store or temporary saturation of the bounded open-store cache. The response may include Retry-After.

Retry idempotent reads after a short backoff. Retry generated-ID POST only with the same idempotency key and identical request. Conditional replacements and deletions may be retried with the same observed revision; a committed competing change then becomes Revision conflict.

If the problem persists, give the operator the X-Request-ID. Wispist does not expose internal error text in the response.