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-authorization 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.required_scope: 403 (TokenScopeRequiredError carrying required_scope) — the refusal require_token_scope emits. A route declaring more than one of these three gates derives the union of their shapes, since any of them can be the one that answers.
• 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).
• checks_content_type: 415 (UnsupportedContentTypeError) — every POST route (see is_post_content_type_refused in http/simple_request.ts).

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.

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.

DELETE blocked by a foreign key constraint.

Authenticated but missing required role.

Request Content-Length header is not a plain run of ASCII digits.

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

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).

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 single-column primary key, so there is no column the row-DELETE can target: either no primary key at all, or a composite one (a single-column WHERE on one member of a composite key over-matches).

Table is excluded from row deletion by policy — the audit trail and the framework's singleton bookkeeping rows (bootstrap_lock, app_settings, schema_version), whose invariants live in the domain layer rather than in a generic storage endpoint. See http/db_routes.ts's NON_DELETABLE_TABLES.

Table name not found in information_schema.

Bootstrap token file not found on disk.

The credential is admitted on this channel, but the specific token's scope does not grant the requested capability.

The body carries required_scope: string in the stable <section>:<id> capability format — rpc:<method> for an action, surface:<name> for a non-RPC surface. Distinct from credential_type_required (which is about the *channel*) and from insufficient_permissions (about the *account's* roles): this one says the account could do it but this token was minted narrower.

A POST whose Content-Type the route refuses: anything but application/json on a JSON route, a CORS-safelisted type or none on a raw_body one. See http/simple_request.ts.

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 (login, bootstrap, password change, signup)
• '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.

Token-scope error — returned by the require_token_scope guard (and its direct-call twin token_scope_surface_denial) when a narrowed api token reaches a capability its scope does not admit. See docs/security.md §Token scoping.

required_scope carries the capability string the route demands, verbatim from its auth.required_scope — surface:audit_stream for a non-RPC surface, rpc:<method> for a bridged action — matching the Rust token_scope_surface_denied_response and the dispatcher's own per-method denial. Third in the family with PermissionError and CredentialTypeRequiredError — each names what the route demanded rather than what the caller holds.

Unsupported content type error — returned when a POST route refuses the request's Content-Type.

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 field is optional: the invalid_json_body case (request body parse failure or non-object root) emits no issues, and the schema-failure cases emit them only in development — production omits them (via dev_only) so error responses don't leak input-schema structure to callers.