Typed Errors

Most APIs handle errors with generic try/catch and status codes. Katman takes a different approach: you declare the errors a procedure can produce upfront, and TypeScript enforces them on both sides.

Error maps

An error map is an object you pass to a procedure's errors field. Each key is an error code, and the value is either a status number or a full config:

import { z } from "zod"

const deleteUser = k.mutation({
  input: z.object({ id: z.number() }),
  errors: {
    NOT_FOUND: 404,                            // just a status code
    FORBIDDEN: {                               // status + typed data
      status: 403,
      message: "You don't own this resource",
      data: z.object({ reason: z.string() }),
    },
  },
  resolve: ({ input, ctx, fail }) => {
    const user = ctx.db.users.findById(input.id)
    if (!user) fail("NOT_FOUND")
    if (user.ownerId !== ctx.user.id) {
      fail("FORBIDDEN", { reason: "Not the owner" })
    }
    return ctx.db.users.delete(input.id)
  },
})

What fail() does

When you define an errors map, the fail() function in your resolver becomes fully typed:

• It only accepts error codes you defined (like "NOT_FOUND" or "FORBIDDEN")
• If the error has a data schema, fail() requires a second argument matching that schema
• If the error has no data, the second argument is optional

fail() throws a KatmanError internally. It has a return type of never, so TypeScript knows that code after fail() won't run — no need for return after it.

Status shorthand vs full config

The two forms:

const errors = {
  // Shorthand: just the HTTP status code
  NOT_FOUND: 404,

  // Full config: status, optional message, optional data schema
  CONFLICT: {
    status: 409,
    message: "Resource already exists",
    data: z.object({ existingId: z.number() }),
  },
}

The shorthand is fine when you just need a code and status. Use the full config when you want to attach structured data to the error.

KatmanError

Under the hood, fail() throws a KatmanError. You can also throw one directly from anywhere — guards, wraps, context factories, or resolvers:

import { KatmanError } from "katman"

// Common codes are mapped to HTTP statuses automatically
throw new KatmanError("NOT_FOUND")           // 404
throw new KatmanError("UNAUTHORIZED")        // 401
throw new KatmanError("BAD_REQUEST")         // 400
throw new KatmanError("FORBIDDEN")           // 403
throw new KatmanError("TOO_MANY_REQUESTS")   // 429
throw new KatmanError("INTERNAL_SERVER_ERROR") // 500

You can also create custom errors with any code:

import { KatmanError } from "katman"

throw new KatmanError("PAYMENT_REQUIRED", {
  status: 402,
  message: "Upgrade to Pro to use this feature",
  data: { plan: "pro", price: 29 },
})

Built-in error codes

These codes are recognized automatically — you don't need to specify a status:

Error JSON format

When an error is sent to the client, it has this shape:

{
  "defined": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "You don't own this resource",
  "data": { "reason": "Not the owner" }
}

The defined field tells you whether this error came from an error map (true) or was thrown manually / unexpectedly (false). This is useful on the client for distinguishing expected business errors from unexpected crashes.

Client-side error handling

Errors thrown on the server are reconstructed as KatmanError instances on the client. You have two ways to handle them:

import { KatmanError } from "katman"

try {
await client.users.delete({ id: 1 })
} catch (error) {
if (error instanceof KatmanError) {
  console.log(error.code)    // "FORBIDDEN"
  console.log(error.status)  // 403
  console.log(error.message) // "You don't own this resource"
  console.log(error.data)    // { reason: "Not the owner" }

  if (error.defined) {
    // This error was declared in the error map — expected business logic
  } else {
    // This was an unexpected error
  }
}
}

import { safe } from "katman/client"

const result = await safe(client.users.delete({ id: 1 }))

if (result.isError) {
console.log(result.error.code) // "FORBIDDEN"
console.log(result.data)       // undefined
} else {
console.log(result.data)       // the deleted user
console.log(result.error)      // null
}

Validation errors

When input validation fails (the data doesn't match your Zod/Valibot schema), Katman automatically returns a 400 BAD_REQUEST with the validation issues:

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Validation failed",
  "data": {
    "issues": [
      { "path": ["email"], "message": "Invalid email" }
    ]
  }
}

You don't need to define this in your error map — it happens automatically whenever input validation fails.

Errors in guards

Guards can throw errors too. A common pattern is an auth guard that throws UNAUTHORIZED:

const auth = k.guard(async (ctx) => {
  const token = ctx.headers.authorization
  if (!token) throw new KatmanError("UNAUTHORIZED")
  const user = await verifyToken(token)
  if (!user) throw new KatmanError("UNAUTHORIZED", { message: "Invalid token" })
  return { user }
})

When a guard throws, the procedure never runs. The error goes straight to the client.

What's next?

• Middleware — learn about guards and wraps in detail
• Client — set up the client that receives these typed errors
• Procedures — the full config form where error maps are defined