Response envelope and error handling

Success helpers

apps/core-api/src/http/respond.ts exports three functions. Controllers use nothing else to write a success response.

export function ok<T>(res: Response, req: Request, data: T, status = 200): void;
export function created<T>(res: Response, req: Request, data: T): void;   // 201
export function noContent(res: Response): void;                            // 204, empty body

ok writes the envelope. requestId is included when the request id middleware ran, which is always the case for routed requests.

{ "ok": true, "data": { "id": "..." }, "requestId": "01JABC..." }

The types live in @perform/types:

export type ApiSuccess<T> = { ok: true; data: T; requestId?: string };
export type ApiError = { ok: false; code: ErrorCode; message: string; requestId?: string; details?: unknown };
export type ApiResponse<T> = ApiSuccess<T> | ApiError;
export type Paginated<T> = { items: T[]; total: number; page: number; pageSize: number };

Pagination

List endpoints take page and pageSize from the query schema and return the Paginated shape inside data:

{ "ok": true, "data": { "items": [], "total": 0, "page": 1, "pageSize": 20 } }

The default pageSize is usually 20. The maximum is set per module in its Zod schema and is not uniform. productListQuery allows up to 500. Read the schema instead of assuming 100.

AppError

@perform/errors exports the one error class services throw.

export class AppError extends Error {
  readonly code: ErrorCode;
  readonly status: number;
  readonly details?: unknown;
  constructor(code: ErrorCode, message: string, options?: { status?: number; details?: unknown });
}

status defaults from the code. Pass options.status only when a code needs a different status.

Codes

ErrorCode is an as const object in @perform/types, re-exported by @perform/errors.

Code	Status	Use
`VALIDATION`	422	Input shape failure. Produced automatically from a `ZodError`.
`BAD_REQUEST`	400	The request is well formed but breaks a rule. Also a wrong OTP code.
`UNAUTHORIZED`	401	Missing or invalid credentials of any kind.
`FORBIDDEN`	403	Authenticated but not allowed: wrong role, plan limit reached, app locked, preview token writing.
`NOT_FOUND`	404	The resource does not exist in this studio.
`CONFLICT`	409	Uniqueness or state conflict.
`RATE_LIMITED`	429	An application level throttle, for example too many OTP sends.
`SERVICE_UNAVAILABLE`	503	A dependency the request needs is down or not configured, for example WhatsApp for an OTP.
`INTERNAL`	500	Anything unexpected.

`details`

details is free form and reaches the client unchanged. The codebase uses a reason string inside it as a machine readable sub code, so clients can branch without parsing messages:

`details.reason`	Thrown by	Code
`PREVIEW_READ_ONLY`	`authenticateTrainee`	`FORBIDDEN`
`APP_LOCKED`	`requireTraineeAppAccess`	`FORBIDDEN`
`PLAN_LIMIT_TRAINEES`, `PLAN_LIMIT_SEATS`	`planLimitError` in `billing.limits.ts`, with `limit`, `count`, `planId`	`FORBIDDEN`
`LINK_UNREADABLE`	`ai/safe-fetch.ts`, with `host` and optionally `status`, `cause`	`BAD_REQUEST`

The trainee app logs the user out on any 401. That is why a wrong OTP is BAD_REQUEST and a frozen subscription is FORBIDDEN with a reason. Do not answer 401 for anything other than a session that is really gone.

The error middleware

errorMiddleware in @perform/errors is registered last in app.ts. It normalizes whatever was thrown, in this order:

AppError

Used as is.

Prisma errors

mapPrismaError recognizes Prisma errors by err.name, not by instanceof, so it works across the two Prisma client packages.

Prisma error	Result
`PrismaClientKnownRequestError` `P2002`	`CONFLICT`, `resource already exists`
`P2025`	`NOT_FOUND`, `resource not found`
`P2003`	`CONFLICT`, `related resource constraint failed`
`P2000`	`BAD_REQUEST`, `value too long for field`
any other known request code	`BAD_REQUEST`, `database request error`
`PrismaClientValidationError`	`BAD_REQUEST`, `invalid database query`
`PrismaClientInitializationError`, `PrismaClientRustPanicError`, `PrismaClientUnknownRequestError`, or a message that looks like a dropped connection	`INTERNAL`, `database unavailable`

Body parser errors

mapBodyParserError handles errors from express.json and express.raw (objects with type, expose: true and a 4xx status). The result is BAD_REQUEST with the parser’s own status: payload too large for 413, invalid request body otherwise.

ZodError

Status 422, code VALIDATION, message validation failed, and details as a list of { path, message } taken from err.issues.

Anything else

Status 500, code INTERNAL, message internal server error. The original message is never sent to the client.

The Prisma mapping is a safety net. Messages from it are generic. A service that expects a unique constraint to fire should catch it and throw an AppError with a useful message.

What is logged

The middleware logs every error with console, not pino:

5xx: console.error('[error]', { requestId, path, method, code, name, message }).
4xx: console.warn('[client-error]', { requestId, path, method, status, code, message }).

The 4xx line exists because the reason for a rejected request otherwise lives only in the response body. The comment in the code describes a trainee retrying a rejected form submit four times and leaving four bare statusCode: 400 lines. The stack is not logged by the middleware. If you need a stack for a failure, log it where it happens with ctx.logger.error({ err }, 'message'). pino serializes err with its stack.

Not found

notFoundMiddleware answers any unmatched route with 404, code NOT_FOUND, message route not found: METHOD /path. Under /v1 an unknown path usually hits replayProtection first. See the warning on Route lanes.

Logging errors outside a request

Two helpers exist and they belong to different package families.

Helper	Package	Use in
`ctx.logger.error({ err, ...fields }, 'message')`	`@perform/logger` (pino)	`apps/core-api` code: services, workers, schedulers
`logError(message, error, context?)` and `serializeError(error)`	`@repo/logs` (consola)	`@repo/*` packages

serializeError returns { name, message, code?, stack? } with the stack cut to four frames. logError logs { error: serializeError(error), ...context }. Nothing under apps/core-api/src calls logError. Use the pino logger from the context there.

Never swallow, but know the best effort pattern

A handler must not hide a failure of its main job. Side effects that must not fail the main job are a different matter, and the code has a consistent shape for them: do the main write, then run the side effect in a try/catch or a .catch that logs and continues. Examples: registerPushToken saves the token and then tries to send pending form pushes. updateFoodPreferences saves and then tries to write a timeline entry. sendTraineeNotification catches everything and returns an empty result, because a push failure must not fail the coach’s action. When you add one, log it with enough context to find it later, and never use it around the main write.

Lanes with their own shape

Surface	Success	Error	Where
`/v1/automation/*`	`{ success: true, message, data }`	`{ success: false, message }`	`automation-api.envelope.ts`
`/v1/public/sign/*`	route specific JSON or PDF bytes	`{ error, code, details? }`, Hebrew messages	`form-sign.routes.ts`, `public-path.ts`
`POST /v1/public/waitlist-leads`	`{ ok: true, id }` with 201	`{ ok: false, code: 'VALIDATION' }` with 400	`public.routes.ts`
`/mcp`	MCP over JSON-RPC	JSON-RPC error objects	`mcp.routes.ts`
`/api/*`	better-auth and oRPC shapes	better-auth `APIError`, `ORPCError`	`@repo/auth`, `@repo/api`

Automation error mapping

automationErrorMiddleware is registered on the automation router, so the global middleware never sees these errors.

ZodError becomes 400 with one readable line: Invalid request: phone is required; .... At most five issues are listed, then (and N more).
AppError uses a narrower status map: UNAUTHORIZED 401, FORBIDDEN 403, CONFLICT 409, RATE_LIMITED 429, SERVICE_UNAVAILABLE 503, INTERNAL 500. Every other code, including NOT_FOUND and VALIDATION, becomes 400, because Make surfaces a 400 with the reason best.
Anything else is 500 with the error’s own message, logged with console.error('[automation-api]', err).

On this lane a non AppError failure sends err.message to the caller. Internal messages can leak that way. Throw AppError with a deliberate message from automation services.

​Success helpers

​Pagination

​AppError

​Codes

​details

​The error middleware

​What is logged

​Not found

​Logging errors outside a request

​Never swallow, but know the best effort pattern

​Lanes with their own shape

​Automation error mapping

Success helpers

Pagination

AppError

Codes

`details`

The error middleware

What is logged

Not found

Logging errors outside a request

Never swallow, but know the best effort pattern

Lanes with their own shape

Automation error mapping