Reference 02 / Errors

Exact failures.

Failures are JSON with a stable error string. There are no HTML error pages and no 429. Most failures are explicit; one important exception is a seam returned as a successful response.

Envelope

error response

{"error":"<reason>"}

Engine exceptions are converted to HTTP 400 and the error string is the exception type and message.

engine failure

{"error":"CapacityError: node cap reached"}

Status codes

Status	When	Body
200	Success, including an `UNKNOWN_SEAM` emission.	Route-specific JSON
400	Invalid JSON, field coercion failure, engine exception, capacity refusal.	`{"error":"..."}`
401	Missing, malformed, expired, revoked, or wrong-instance credential.	`{"error":"..."}`
403	Authenticated but wrong tier or excluded capability.	`{"error":"..."}`
404	Unknown path.	`{"error":"not found"}`
409	The optional accounts or security node is not enabled.	`{"error":"..."}`

Authentication failures

A 401 is a credential failure; a 403 is a permission failure. The reason strings are stable: malformed, bad_signature, wrong_instance,unknown_account, account_inactive, stale_epoch,expired, tier_mismatch, and capability_denied.

See Authentication for the full model.

Seam is not an error

Asking for a relation that does not exist is a valid answer. /emit with an absent anchor returns HTTP 200 and a seam verdict:

unknown anchor

{"verdict":"UNKNOWN_SEAM (anchor not in store)","emitted_text":"UNKNOWN_SEAM"}

This is different from a 404. A 404 means the route does not exist; a seam means the route exists and the relation does not.

Retries

There are no idempotency keys.
GET routes are safe to repeat.
Every POST replays the operation. A retried observation is admitted again; a retried sequence is replayed.
There is no Retry-After and no 429. The server does not rate-limit at the HTTP layer.
If a request times out, read the instance state before retrying a mutation.

Operational bounds

The server is single-threaded. One long call blocks the others; calls are serialized for deterministic ordering.
There is no explicit request-body size cap beyond process memory. Keep payloads small.
There is no CORS configuration. Browser calls from another origin will be blocked; use a server-side client.
There is no HTTP route to delete nodes, clear the substrate, or reset the seam latch.
Node capacity is reported by /status.capacity. Admission beyond the cap fails with 400.
Persistence is an instance concern. When enabled, accepted mutations survive restarts; client-side retries do not.

The server validates JSON syntax and field coercion, not a full request schema. A missing or mistyped field can be coerced to an empty string or zero. Send every field explicitly and validate on the client.

Start

Build