#Responses and errors

What a handler returns: values, response helpers and errors. For a guide, see Responses and Errors.

#What a handler returns

#Response helpers

All of them are exported by @dotpress/core. init accepts status and headers; headers set on ctx.res are merged.

handler: ({ req, res }) => {
  res.setHeader('Cache-Control', 'no-store')
  return json(created, { status: 201, headers: { Location: `/tasks/${created.id}` } })
}

redirect() sends the location as given: behind a proxy, build it with ctx.publicPath('/login').

#stream()

The source is a ReadableStream, an iterable, an async iterable, or a function returning one. A function receives { signal }, aborted when the client disconnects. Chunks are strings, encoded as UTF-8, or Uint8Array. A string or a Uint8Array given as the source is one chunk.

return stream(async function* ({ signal }) {
  for await (const row of db.export({ signal })) yield `${row.csv}\n`
}, { contentType: 'text/csv' })

#sse()

The source yields events, or strings sent as data:

sse() sets Content-Type: text/event-stream, Cache-Control: no-cache and X-Accel-Buffering: no (no buffering in nginx).

#file()

body is a Uint8Array, an ArrayBuffer, a Blob or a ReadableStream. The content type defaults to the type of the Blob, else application/octet-stream. Content-Length is set when the size is known, and filename is encoded for non-ASCII names.

return file(pdf, { filename: 'invoice-2026-001.pdf', contentType: 'application/pdf' })

#Error helpers

Each one returns an HttpError: return notFoundError() or throw notFoundError(). message replaces the default message; data adds details to the body.

#Errors produced by Dotpress

Validation issues have this shape:

interface ValidationIssue {
  source: 'params' | 'query' | 'body' | 'files'
  path: (string | number)[]
  code: string // the Zod issue code: 'invalid_type', 'too_small'…
  message: string
}

#Error body

Every error response has the same JSON body:

interface ErrorBody {
  status: number
  error: string
  message: string
  data?: Record<string, unknown>
}

{ "status": 404, "error": "NOT_FOUND", "message": "Task not found" }

With exposeErrors: true, the data of a 500 holds the name, message and stack of the error, and the issues of an invalid response. Never in production.

#HttpError

class HttpError extends Error {
  constructor(
    status: number, // 400 to 599
    code: string,
    message: string,
    data?: Record<string, unknown>,
    options?: { cause?: unknown }
  )
  readonly status: number
  readonly code: string
  readonly data: Record<string, unknown> | undefined
  toJSON(): ErrorBody
}

Subclass it, or wrap errorResponse(), for the errors of your domain:

export const quotaExceededError = (limit: number) =>
  errorResponse(402, 'QUOTA_EXCEEDED', 'Quota exceeded', { limit })

isHttpError(value) recognizes an HttpError, even one created by another copy of @dotpress/core. toErrorBody(error) returns its body.

Headers set on ctx.res are kept on the response of an HttpError, not on the 500 of an unexpected error. See Custom errors and Unexpected errors.