errorResponse

errorResponse(error, requestId) is the single format Meeko uses to respond to API, RPC, local dispatch or adapter failures: a JSON Response with { code, status, requestId } and the x-request-id header. An ApiError keeps its code and status; any other error becomes 500 INTERNAL_ERROR, without its message or stack trace, which only server observers see.

Use it in a custom host or server middleware so your errors have the same shape as Meeko's and the client receives them as a ClientError with their code.

Usage#

import { ApiError, errorResponse } from "@meekojs/meeko/server";

const response = errorResponse(new ApiError("NOT_FOUND", 404), crypto.randomUUID());
// 404 {"code":"NOT_FOUND","status":404,"requestId":"…"} with x-request-id

Type#

function errorResponse(error: unknown, requestId: string): Response

Parameters#

Return value#

A Response with content-type: application/json; charset=utf-8 and x-request-id:

Examples#

Middleware that stops execution using Meeko's format#

// server/middleware/05-api-key.ts
import { ApiError, defineServerMiddleware, errorResponse } from "@meekojs/meeko/server";

export default defineServerMiddleware(async (request, next) => {
  const { pathname } = new URL(request.url);
  if (pathname.startsWith("/api/partners/") && request.headers.get("x-api-key") !== process.env.PARTNER_API_KEY) {
    return errorResponse(new ApiError("INVALID_API_KEY", 401), crypto.randomUUID());
  }
  return next();
});

In the browser, api.partners.* rejects with a ClientError whose code is INVALID_API_KEY.

Field errors that reach useForm#

import { ApiError, errorResponse } from "@meekojs/meeko/server";

export const conflict = errorResponse(
  new ApiError("EMAIL_TAKEN", 409, { issues: [{ path: "email", message: "That email already has an account." }] }),
  crypto.randomUUID(),
);
// 409 {"code":"EMAIL_TAKEN","status":409,"requestId":"…","issues":[{"path":"email","message":"That email already has an account."}]}

A custom host handler that never rejects#

async function handle(request: Request): Promise<Response> {
  const requestId = crypto.randomUUID();
  try {
    return await route(request);
  } catch (error) {
    logger.error({ requestId, error }); // the private message, only on the server
    return errorResponse(error, requestId);
  }
}

Common mistakes#

Send the error message to the client#

catch (error) { return Response.json({ error: String(error) }, { status: 500 }); }

A database or service error may contain queries, paths or personal data. errorResponse only publishes the code; details go to onError with the same requestId, which the user can quote.

catch (error) { app.reportError(error, requestId); return errorResponse(error, requestId); }

Throw an Error with a status#

throw Object.assign(new Error("No encontrado"), { status: 404 });

Only ApiError keeps the status: this responds with 500 INTERNAL_ERROR and reaches onError as a server failure.

throw new ApiError("NOT_FOUND", 404);

issues in a 5xx#

throw new ApiError("BROKEN", 503, { issues: [{ path: "email", message: "The email service failed." }] });

The response is 503 {"code":"BROKEN",…} without issues: field messages only travel with a 4xx status.

throw new ApiError("MAIL_UNAVAILABLE", 503);

Notes#

• Security. Never writes the message, stack trace or cause of an error other than ApiError. An ApiError's message (its third argument) is also internal.
• Observers. errorResponse does not notify anyone: Meeko's dispatcher also calls onError for 5xx responses. In a custom host, report the error yourself with the same requestId.
• Client. The browser receives the body as a ClientError (code, status, requestId, issues); isClientError(error, "CODE") checks it.

Related#

• ApiErrorPublic API, RPC, Socket and loader error, delivered to the client with its code, status and, since 1.5, field messages.
• SessionRevokedErrorThe 401 SESSION_REVOKED ApiError for a session revoked, rotated or expired during the request, and the abort reason of context.signal.
• SessionSecurityErrorA mutation failed the session's Origin or CSRF check, with code INVALID_ORIGIN or INVALID_CSRF; API and RPC responses convert it to 403.
• ClientErrorThe error API, RPC and Socket clients use to reject an error response from the server, with its code, status, requestId and per-field issues.
• ErrorsMeeko as a full-stack framework
• API and RPCMeeko as a full-stack framework
• Form validation errorsMeeko as a full-stack framework