Spec: Error registry & response envelope

Every REST response uses one envelope, and every error carries a machine-readable code from a published registry. The registry is wire contract: hosts, widgets, and agents branch on these codes, so the codes come with evolution rules you can build against.

Registry document: error-registry.v1.json — the code list plus both envelope schemas, in one fetchable file.

The envelope

Success:

{ "status": "ok", "payload": { "...": "route-specific" } }

Error:

{ "status": "error", "code": "ROWS_LIMIT_EXCEEDED", "message": "…", "issues": [ … ] }

• code is the field to branch on; message is a human sentence and not contract — its wording may change in any release.
• issues appears when the failure is a validation error, as an array of structured issue objects (path / message / code), useful for display and debugging.
• Per-route payload shapes are in the OpenAPI document.

The registry

The registry document enumerates every code the import service emits, grouped in source by concern: request/auth basics, license and entitlement, storage, changesets, ingest and decoding, target catalogs, catalog scanning, questions and agent answers, reference resolution, webhooks, and self-host preflight findings.

Two properties make the list dependable:

• It is enforced in both directions. A test suite asserts that every code the service emits is registered, and that every registered code is still emitted somewhere — the published list can be neither incomplete nor stale.
• It has evolution rules. Adding a code is a feature and may happen in any release. Renaming or removing one is a breaking change, flagged and released under the breaking-change policy.

What a client must do

1. Branch on code, never on message.
2. Tolerate unknown codes. Requests that fail before routing (malformed body, unknown path) can carry transport-level codes outside the registry, and new registry codes may appear in any release. On an unrecognized code, fall back to the HTTP status semantics of the response.
3. Do not treat issues as stable shape beyond “array of objects with path, message, and code” — display it, log it, but branch on the envelope code.

---

This specification page and the linked registry document are licensed CC BY 4.0 — see the spec overview for scope.