Error Codes

16.1 Error Code Reference

StemJSON uses a structured error code system for repository and service failures. Error codes are accessible in action failure chains via @{actionId.code}.

Category	Code	Description
General	unknown	Unclassified error.
General	cancelled	Operation was cancelled.
General	timeout	Operation timed out.
General	decodingFailed	Response could not be decoded.
General	encodingFailed	Request body could not be encoded.
General	missingData	Expected data was absent in the response.
General	dependencyNotRegistered	A referenced dependency id was not found in the registry.
Network	invalidResponse	Server returned an unrecognizable response.
Network	noConnection	No network connectivity.
Network	invalidURL	The endpoint URL is malformed.
Network	badRequest	HTTP 400 — request was rejected by the server.
Network	notAuthenticated	HTTP 401 — authentication required.
Network	notAuthorized	HTTP 403 — access denied.
Network	notFound	HTTP 404 — resource not found.
Network	conflict	HTTP 409 — resource conflict.
Network	internalServer	HTTP 500 — server-side error.
Network	serviceUnavailable	HTTP 503 — server temporarily unavailable.
Storage	documentExists	Document already exists (local repo).
Storage	documentNotFound	Document not found (local repo).
Storage	noDocumentId	Operation requires a document id but none was provided.
Storage	savingFailed	Could not persist the document.
Storage	deletionFailed	Could not delete the document.
Security	keychainAccess	Keychain access error (secured repo).
Security	itemNotFound	Key not found in keychain.
Security	userCanceledAuth	User canceled biometric / passcode authentication.
Security	enclaveLocked	Secure enclave is locked.

16.2 Validation Log Contract

Validators emit human-readable log records during payload validation and schema checks. Each record MUST include a classified, actionable message — a generic placeholder (e.g. "Unexpected error") in a public log record is non-conforming.

Record fields (normative):

Field	Required	Description
severity	REQUIRED	One of: bingo, info, note, warning, error, critical (see §17).
context	REQUIRED	A path-like breadcrumb identifying where the issue occurred (e.g. component id: 'feed_list' → general → ...).
publicMessage	REQUIRED	Short, author-facing message. MUST name the error category (type mismatch, missing key, expression parse error, invalid source URL, …) and, where available, the offending value or token. MUST NOT contain file paths, URLs, or OS-internal identifiers.
privateDetails	Optional	Additional diagnostic text that MAY contain paths or low-level descriptions. Implementations MAY surface this only in development builds.

Category coverage (normative):

Implementations MUST produce classified public messages for at least the following error classes thrown during validation:

• Schema decoding failures — missing required keys, type mismatches, invalid enum values, malformed source strings.
• Expression parse failures — unexpected tokens, missing operators, excessive nesting.
• Package structure failures (for zip-packaged modules) — missing main.json, multiple main.json at the archive root, corrupt archive.
• Dependency resolution failures — unknown repository / service id, cyclic dependency.

Implementations SHOULD additionally emit warning-severity records for the following authoring pitfalls — they do not block rendering but produce broken or unintuitive UI:

• Out-of-domain initial state value. Any initial state literal that is statically provably outside the valid domain of the input component bound to it (§11.1). The check generalises across all bound input components — sliders, pickers, toggles, datepickers, and any future component that declares a domain.
• Source string missing scheme prefix. Any value supplied to a source-accepting field (_source, _image, _placeholder, etc.) that lacks a <scheme>:// prefix, with the documented _tabImage exception (§6.4). The check generalises across all current and future schemes.
• Ambiguous string value form. Any string value at a value-accepting field that mixes literal text and reference markers without {{ }} wrapping, i.e. that does not match exactly one of: literal / single bare reference / {{ … }} expression (§6.2).

Unclassified failure paths SHOULD be tracked and fixed at their source rather than handled in a generic fallback.