Skip to content

The error envelope ​

Kata produces one error shape. Every 4xx and 5xx response — validation failures, your own domain errors, output mismatches, uncaught throws — comes back as the same JSON envelope:

ts
type ErrorBody = {
  error: string                          // stable, machine-readable code
  message: string                        // human-readable description
  issues?: Record<string, FieldIssue[]>  // structured field errors, keyed by input section
}
  • error — the discriminator a client switches on ('not_found', 'validation_failed', 'internal_error'). It never holds a human sentence.
  • message — a human-readable description. Always present.
  • issues — present only when there are structured field errors (today: input validation).

Why force every failure into one shape? Because it lets a client write one error handler instead of one per endpoint. Whatever goes wrong, the caller reads error to decide what happened and message to show a human — never guessing at a different body shape for each route. And this is enforced by the runtime, not by convention: both ends of every route are validated, and each failure mode maps to this envelope. The two automatic ones come first; the ones you write come after.

StageWhenOn failure
Inputbefore the handler runs422 validation_failed
Handler throwsany escape from middleware or handler500 internal_error
Outputafter the handler returns a value500 internal_output_shape_mismatch (mode-dependent)
Your 4xxyou return c.error(...) / c.json(...)your status

A request whose body is non-empty but not valid JSON is rejected before the input stage with 400 validation_failed (message: "Malformed JSON body"); an empty or absent body instead reads as undefined and lets the schema decide.

Unknown route and wrong method: the built-in 404 / 405 ​

Two failures happen before any of the stages above — no route matched, so there is no input schema and no handler of yours to run. Kata answers them itself, through the same envelope, with no configuration required.

A request to a path no route declares answers 404:

json
{ "error": "not_found", "message": "Route not found" }

A request with the wrong method on a path some route does declare answers 405, with an Allow header listing the methods the path accepts:

json
{ "error": "method_not_allowed", "message": "Method not allowed" }

Both run the app-level (global) middleware chain first — the same fallback that lets a global cors() answer an OPTIONS preflight even against a path no route declares (see CORS preflight for how a registered path's preflight is normally answered) — and both pass through the same final step as every other response, so the X-Request-Id correlation header is present here too.

The 422 validation envelope ​

input is validated before your handler — a 422 is Kata's way of saying "you sent something the route's input schema rejected." On failure Kata never calls the handler; it responds 422 with error: "validation_failed", the message "Request input validation failed", and an issues object keyed by the input section that failed (params / query / body / headers). Each key holds an array of field issues.

For the POST /users body { "name": "", "email": "not-an-email" } against CreateUserBodySchema, the response is (this shape is asserted by examples/hello's users.hurl; the literal message strings are Zod's):

json
{
  "error": "validation_failed",
  "message": "Request input validation failed",
  "issues": {
    "body": [
      { "path": "name",  "code": "too_small",      "message": "String must contain at least 1 character(s)" },
      { "path": "email", "code": "invalid_string", "message": "Invalid email" }
    ]
  }
}

A query failure looks the same, just keyed under query instead of body. This is what an invalid z.enum(...) value produces — the commonest query shape — for GET /todos?status=archived against z.object({ status: z.enum(['open', 'done']) }):

json
{
  "error": "validation_failed",
  "message": "Request input validation failed",
  "issues": {
    "query": [
      {
        "path": "status",
        "code": "invalid_enum_value",
        "message": "Invalid enum value. Expected 'open' | 'done', received 'archived'",
        "received": "archived"
      }
    ]
  }
}

The 422 is fixed, and it is not configurable

Automatic schema validation — any input section that fails safeParse — always answers 422. The only automatic 400 is a malformed (non-JSON) body; see Gotchas. Your own c.error(...) is the only thing that can produce a 400, and there is no option, hook, or config anywhere in defineRoute or createApp that changes the automatic 422.

If a contract you're implementing demands 400 for what is really a schema failure, the way out is to loosen the input schema so it always parses, then check the shape by hand in the handler and return c.error(..., { status: 400 }) yourself — trading the automatic check for a manual one that controls its own status.

The FieldIssue shape ​

Every entry under issues is a FieldIssue:

ts
type FieldIssue = {
  path: string       // dot/bracket path: "email", "user.profile.age", "items[1].qty"
  message: string    // Zod's human-readable message
  code: string       // Zod issue code: "too_small", "invalid_type", "invalid_string", …
  expected?: unknown // present when the Zod issue carries it (e.g. invalid_type, invalid_enum_value)
  received?: unknown // present when the Zod issue carries it (e.g. invalid_type, invalid_enum_value)
}

Rules to keep straight:

  • path uses dot notation for nested objects and [n] for array indices. A root-level error has an empty path: "".
  • expected / received appear when the underlying Zod issue carries them (e.g. invalid_type, invalid_enum_value) and are omitted otherwise.
  • Issues are reported in source order. When more than one section is invalid (e.g. both params and body), each gets its own key under issues.

Reuse the formatter

If you validate something yourself — a webhook payload, a re-parsed query, a cross-field rule — and want the response to match this exact shape, formatZodIssues(error: ZodError): FieldIssue[] is exported from @katajs-framework/core. Build the envelope with c.error('validation_failed', 'Request input validation failed', { status: 422, issues: { body: formatZodIssues(parsed.error) } }).

Output validation and internal_output_shape_mismatch ​

When your handler returns a plain value (not a Response), Kata runs it through the route's output schema before serialising — a last check that the server is actually sending the shape it promised. What happens on a mismatch is deliberately configurable, because the right reaction differs by environment; it is set by the app's outputValidation mode (ADR-0009):

ModeOn mismatchIntended environment
strictLog the issues, return 500 internal_output_shape_mismatchdev / test / CI
logLog the issues, send the handler's data through unchangedproduction
offSkip output validation entirelyperf-critical opt-out

The three modes trace the tension between catching bugs and staying up: strict fails loudly, so a wrong shape can never slip past in dev or CI; log keeps production serving, letting a benign drift become a log line instead of an outage; off removes the check entirely where every microsecond counts.

The mode is resolved once at createApp, first match wins:

  1. the explicit outputValidation passed to createApp,
  2. the KATA_OUTPUT_VALIDATION env var when it names a valid mode,
  3. derived from NODE_ENV — production → log, otherwise strict.
ts
const app = createApp({ modules: [users], outputValidation: 'strict' })

In strict mode the Zod issues are logged server-side (through your injected logger if one is registered, else console.error) and the response is exactly:

json
{ "error": "internal_output_shape_mismatch", "message": "Response did not match the declared output schema" }

with status 500. This catches "the handler returned almost the right shape" before it reaches a client. In log mode the issues are still logged, but the handler's data is sent through unchanged — a benign shape drift in production degrades to a log line instead of a hard 500. In off mode there is no safeParse and no Zod transform; the data passes through as-is.

The mismatch is never leaked to the client

On a strict mismatch the client receives the generic internal_output_shape_mismatch envelope. The offending Zod issues are logged server-side only — field names and internal shape never cross the wire.

Uncaught throws: internal_error ​

A throw that escapes any middleware or handler is caught by Kata's global error boundary and serialised through the same envelope:

json
{ "error": "internal_error", "message": "Internal server error" }

with status 500 and Content-Type: application/json — never Hono's default text/HTML 500 page. That boundary exists so a bug can never leak a stack trace or an HTML error page to a client: the raw error is logged server-side, and the underlying message is never surfaced.

The error handed to your logger.error arrives pre-flattened, not as a raw Error: { err: { name, message, stack?, cause?, errors? } }, with cause chains walked (depth-capped, cycle-safe) and AggregateError.errors expanded. A raw Error serialises to "{}" under the naive JSON.stringify-based logger most structured loggers start as — its message and stack are non-enumerable — so Kata never hands one to your logger directly.

Reserve throwing for genuine bugs. For failures the client should understand, return c.error(...).

Testing this without a crash route

Exercising this path needs a route that always throws — but that route should never ship on the app's real surface (a GET /diagnostics/boom reachable in production). Testing the error boundary without a crash route shows the pattern: build the throwing route inside the test file, with the app's own createApp/defineRoute, and never add it to main.ts's modules array.

Custom statuses: c.error and c.json ​

For domain errors — not found, forbidden, conflict — return a Response from the handler. The idiomatic way is c.error(code, message, extra?), which builds the unified envelope; c.json(value, status?) is the escape hatch for a custom shape. Both are available on the route and middleware contexts.

ts
return c.error('not_found', 'No user with that id', { status: 404 })
// → 404  { "error": "not_found", "message": "No user with that id" }

c.error's signature:

ts
c.error(code: string, message: string, extra?: ErrorExtra): Response

type ErrorExtra = {
  status?: number                        // defaults to 400
  issues?: Record<string, FieldIssue[]>  // attach structured field errors
}
  • The code argument becomes the wire error field.
  • status rides inside extra and defaults to 400.
  • Attach structured field errors via extra.issues (the same FieldIssue[] shape as the 422 envelope).

The distinction that governs the response pipeline (the same one from Routes & schemas):

  • return a value → validated against output, sent as 200.
  • return c.error(...) / c.json(body, status) → carries its own status.

Returned responses and the output schema ​

With a single output schema, a returned Response (including c.error) short-circuits the route and is not checked against it — which is precisely why an error body is allowed to differ from your success shape.

ts
export const getUserRoute = defineRoute({
  method: 'GET',
  path: '/users/:id',
  input: { params: z.object({ id: z.string() }) },
  output: UserSchema,
  handler: async (c) => {
    const user = await getUser(c.input.params.id)
    if (!user) return c.error('not_found', 'User not found', { status: 404 }) // not validated
    return user                                                               // validated against UserSchema
  },
})

To type and validate error bodies too, declare output as a status→schema map (ADR-0011). Kata ships ErrorBodySchema for exactly this — the Zod mirror of the unified envelope:

ts
import { ErrorBodySchema } from '@katajs-framework/core'

export const getUserRoute = defineRoute({
  method: 'GET',
  path: '/users/:id',
  input: { params: GetUserParamsSchema },
  output: { 200: UserSchema, 404: ErrorBodySchema },
  handler: async (c) => {
    const user = await getUser(c.input.params.id)
    if (!user) return c.error('not_found', 'User not found', { status: 404 })
    return user
  },
})

In the map form: a plain return is the 200 body; c.json(body, 201) is validated against output[201]; a c.error(...) whose status is declared is validated against that status's schema. Undeclared statuses still pass through unvalidated. The original Response is forwarded verbatim on success — Kata never re-serialises a response your handler built, so a header or content type you set is preserved. The RPC client narrows by status: InferResponseType<call, 404>. See defineRoute for the full output contract.

The wrong schema behind an error status silently breaks that error

Declaring a status opts it into validation, and c.error(...) always emits the unified { error, message } envelope. So if the schema under a 4xx key is anything else — the success DTO, copied one line up by accident — the envelope fails its own declared schema, and what the caller gets depends on the mode rather than on your handler:

ts
output: { 200: TodoSchema, 400: TodoSchema }   // ← 400 is not the envelope
handler: (c) => c.error('invalid_filter', 'Unknown filter', { status: 400 }),
  • strict (the default outside production) — your 400 is replaced by 500 { "error": "internal_output_shape_mismatch", … }. The domain error never reaches the caller.
  • log (the default in production) — the malformed 400 ships to the caller as written, and only a server-side log line records the mismatch.

Neither mode is the behaviour you wanted, and the one that hides it is the one production runs. Put ErrorBodySchema — or a refinement of it — behind every declared 4xx/5xx, and the mismatch becomes a compile-time concern instead of a runtime one.

What's automatic vs. what you write ​

SituationStatusWho produces it
No route matches the path404Kata (automatic)
Path matches, method doesn't405Kata (automatic)
Input fails its schema422Kata (automatic)
Handler returns a value matching output200Kata
Handler returns c.error(...) / c.json(body, status)your statusyou
Handler return value fails output500 (mode-dependent)Kata (automatic)
Handler throws500Kata's error boundary

Gotchas ​

  • A malformed JSON body returns 400 validation_failed (message: "Malformed JSON body") before schema validation — the unparseable bytes never reach your body schema. An empty or absent body is different: it reads as undefined, so the body schema decides (an optional body passes; a required one → 422).
  • Every response carries a correlation id. Success or error, Kata echoes an X-Request-Id header (reusing a well-formed inbound one, otherwise a fresh UUID). See Lifecycle.
  • status is not a positional argument on c.error. It lives inside extra and defaults to 400 — c.error('not_found', '…') without a status returns 400, not 404.

See also ​

Open-source — license TBD. Built on Hono + Zod.