Typed Errors

Most APIs handle errors with generic try/catch and status codes. Silgi 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 .$errors() on the builder. 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
  .$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 errors via .$errors(), 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 SilgiError 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.

SilgiError

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

import { SilgiError } from 'silgi'

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

You can also create custom errors with any code:

import { SilgiError } from 'silgi'

throw new SilgiError('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 SilgiError instances on the client. You have two ways to handle them:

import { SilgiError } from "silgi"

try {
await client.users.delete({ id: 1 })
} catch (error) {
if (error instanceof SilgiError) {
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 "silgi/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), Silgi 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 = s.guard(async (ctx) => {
  const token = ctx.headers.authorization
  if (!token) throw new SilgiError('UNAUTHORIZED')
  const user = await verifyToken(token)
  if (!user) throw new SilgiError('UNAUTHORIZED', { message: 'Invalid token' })
  return { user }
})

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

Typed guard errors

Guards can declare their own error maps. When a procedure uses that guard, the errors automatically merge — both in TypeScript inference and in the OpenAPI spec:

const auth = s.guard({
  errors: { UNAUTHORIZED: 401 },
  fn: async (ctx) => {
    const token = ctx.headers.authorization
    if (!token) throw new SilgiError('UNAUTHORIZED')
    return { user: await verifyToken(token) }
  },
})

const rateLimit = s.guard({
  errors: { RATE_LIMITED: 429 },
  fn: (ctx) => {
    if (tooManyRequests(ctx)) throw new SilgiError('RATE_LIMITED')
  },
})

const createUser = k
  .$use(auth, rateLimit)
  .$errors({ CONFLICT: 409 })
  .$resolve(({ fail }) => {
    // fail() accepts all three: 'UNAUTHORIZED' | 'RATE_LIMITED' | 'CONFLICT'
    fail('CONFLICT')
  })

This gives you three things:

• Type safety — fail() in the resolver knows about guard error codes, not just procedure error codes
• OpenAPI — the generated spec includes 401, 429, and 409 responses for this endpoint
• Runtime — fail('UNAUTHORIZED') produces the correct 401 status code

What's next?

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