http/error_schemas.ts

Authorization-phase failure shapes. Surfaced when the dispatcher's apply_authorization_phase rejects a request before the handler runs — the route is acting-aware (input declares acting?: ActingActor or auth requires role_grants), but actor resolution failed.

400: actor_required (with available[]) for unspecified-actor on a multi-actor account; actor_not_on_account for a supplied actor id that doesn't belong to the authenticated account.

500: no_actors_on_account for a signup-invariant violation (the actor list enumerated empty); account_vanished for a torn-read race (account/actor row deleted between credential validation and the dispatcher's follow-up read).

Used by derive_error_schemas when auth.actor !== 'none' so the merged error surface matches what the dispatcher actually emits.

Base API error — all JSON error responses have at least {error: string}.

Credential-type error — returned by the dispatcher's post-authorization credential gate (and the require_credential_types REST middleware) when the request's credential type isn't in the route's auth.credential_types allowlist.

required_credential_types carries what the route declared (['daemon_token'] for keeper; future gates carry their own labels). Symmetric with PermissionError's required_roles: clients see what the route demanded, not what their credential is.

Derive error schemas from a route's auth requirement, input schema, and rate limit config.

Returns the error schemas that middleware will auto-produce for this route. Route handlers can declare additional error schemas via RouteSpec.errors; explicit entries override auto-derived ones for the same status code.

Derivation rules under the new flat-record auth shape: - Has input / params / query schema: 400 (ValidationError). - auth.account === 'required' or auth.actor === 'required': 401 (ApiError) — pre-validation 401 fires when the credential isn't there. 'optional' does not derive 401. - auth.roles?.length: 403 (PermissionError carrying required_roles). - auth.credential_types?.length: 403 (CredentialTypeRequiredError carrying required_credential_types — symmetric with PermissionError). Today the only credential gate is keeper; future gates reuse the literal. - auth.actor !== 'none' ('optional' or 'required'): extends 400 with ActorRequiredError / ActorNotOnAccountError and adds 500 union of NoActorsOnAccountError / AccountVanishedError. The dispatcher's authorization phase emits these whenever it tries to resolve an actor. - rate_limit: 429 (RateLimitError with retry_after).

Token references a deleted account.

Authentication validated an account, but a follow-up read in the authorization phase came back null — the account or its named actor row was deleted between the credential check and the dispatcher's build_request_context / build_account_context step. Torn read, not a missing-actor invariant violation. Surfaced as 500 so the operator sees the race signal; clients can retry. Distinct from ERROR_ACCOUNT_NOT_FOUND (stale token referencing a long-deleted account, raised at credential validation) and ERROR_NO_ACTORS_ON_ACCOUNT (the actor list enumerated empty).

Supplied acting field does not name an actor on the authenticated account.

Multi-actor account requires the request to carry an explicit acting field naming the actor the request is acting as, so the dispatcher's authorization phase doesn't pick a default actor silently. Returned with the available actors so the client can prompt.

Bootstrap lock already acquired — system already bootstrapped.

No valid session or bearer token.

Bearer token sent with Origin/Referer header (browser context).

Bootstrap endpoint called but no token path configured.

Route requires a credential type the request didn't arrive on. Symmetric with ERROR_INSUFFICIENT_PERMISSIONS + required_roles: the body carries required_credential_types: ReadonlyArray<string> — what the route demanded, not what arrived. Today the only credential gate is keeper (['daemon_token']); future gates (agent_token, group_actor_token) reuse the same literal and label themselves through the array.

Database health-check query failed (connectivity or query error).

Request origin not in allowlist.

Request referer not in allowlist.

DELETE blocked by a foreign key constraint.

Authenticated but missing required role.

Username or password is wrong (intentionally vague for enumeration prevention).

Daemon token header present but malformed or not matching current/previous token.

Query parameter event_type is not a valid audit event type.

Request body is not valid JSON or not an object.

URL query params failed Zod validation.

Request body failed Zod validation.

URL path params failed Zod validation.

Bearer token failed validation (missing, malformed, or revoked).

An account already exists with this invite's email.

An account already exists with this invite's username.

An unclaimed invite already exists for this email or username.

Invite not found (for delete operations).

Daemon token valid but keeper account not yet resolved (pre-bootstrap).

Keeper account ID set but account row not found.

Authenticated account exists but has no actors. Server invariant violation — signup / bootstrap always create an actor in the same transaction. Surfaced from the dispatcher's authorization phase as a 500 so the operator sees the corruption signal rather than a confusing 4xx. Distinct from ERROR_ACCOUNT_VANISHED: the actor list was enumerated successfully and came back empty.

No unclaimed invite matches the signup credentials.

Request body exceeds the maximum allowed size.

Rate limiter rejected the request.

Role grant ID not found or not owned by the target actor.

Admin tried to grant a role that is not web-grantable.

Row with the given PK value not found.

Signup conflict — username or email already taken (intentionally vague for enumeration prevention).

Table has no primary key constraint (cannot delete by PK).

Table name not found in information_schema.

Bootstrap token file not found on disk.

Foreign key violation error — returned when a delete is blocked by references.

Payload too large error — returned when the request body exceeds the size limit.

Permission error — returned by require_role() and the dispatcher's post-authorization role gate when the actor's role_grants don't include any of the route's auth.roles.

required_roles carries the full disjunction the route declared (auth.roles from the new flat-record shape). Single-role specs surface as a one-element array; multi-role disjunctions show every admittable role so clients can render targeted copy ("requires admin or steward").

Rate limit error — returned when a rate limiter rejects the request.

Rate limit key type — declares what a route or RPC action's rate limiter is keyed on.

- 'ip' — per-IP rate limiting (bootstrap, password change, bearer auth) - 'account' — per-account rate limiting. On REST auth routes the key is the submitted identifier (login). On RPC actions (post-auth) the key is the resolved actor id (request_context.actor.id) — separate namespace. - 'both' — both keys.

Error schema map — maps HTTP status codes to Zod schemas.

Used on RouteSpec.errors and internally by derive_error_schemas.

Input validation error — returned when params / query / body fails Zod parsing, or when the request body is not valid JSON.

error is one of the four validation codes the framework emits. issues carries Zod's validation issues for diagnostic display on the three schema-failure cases (invalid_request_body, invalid_route_params, invalid_query_params). The invalid_json_body case (request body parse failure or non-object root) emits no issues, so the field is optional.