@remit/backend 0.0.116 → 0.0.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.116",
+  "version": "0.0.117",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/src/error.test.ts

@@ -1,11 +1,15 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import type { FolderRoleConflict } from "@remit/api-openapi-types";
+import type { ApiError, FolderRoleConflict } from "@remit/api-openapi-types";
 import {
+	BadRequestError,
 	ClientError,
+	ConflictError,
 	FolderRoleUnresolvedError,
 	ForbiddenError,
+	NotFoundError,
 	UnhandledError,
+	UnrecoverableBodyError,
 } from "@remit/data-ports/errors";
 import { NO_TRASH_FOLDER_REASON } from "@remit/data-ports/folder-role";
 import { CanonicalMailboxRole } from "@remit/domain-enums";
@@ -15,6 +19,72 @@ import { handleError } from "./error.js";
 const parseBody = (body: string): Record<string, unknown> =>
 	JSON.parse(body) as Record<string, unknown>;
 
+// One shape for every error the API answers with (issue #371): flat, always a
+// `code`, always a `message`. A status class that reaches a client without a
+// code leaves it branching on prose.
+describe("the wire shape of a refusal, per status class", () => {
+	const cases: ReadonlyArray<[string, Error, number, string]> = [
+		[
+			"400",
+			new BadRequestError("confirmEmail is required"),
+			400,
+			"invalid_request",
+		],
+		["401", new ClientError("Session expired"), 401, "unauthorized"],
+		["403", new ForbiddenError("Not your account"), 403, "forbidden"],
+		["404", new NotFoundError("Mailbox not found: mb-1"), 404, "not_found"],
+		[
+			"409",
+			new ConflictError("An update is already in progress."),
+			409,
+			"conflict",
+		],
+		[
+			"422",
+			new UnrecoverableBodyError("This message's body could not be read."),
+			422,
+			"unprocessable_entity",
+		],
+	];
+
+	for (const [name, error, statusCode, code] of cases) {
+		it(`answers ${name} with a flat code and message`, async () => {
+			const response = await handleError(error);
+
+			assert.equal(response.statusCode, statusCode);
+			assert.deepEqual(parseBody(response.body), {
+				code,
+				message: error.message,
+			});
+		});
+	}
+
+	// A 5xx is the one class whose message is not the thrower's. Those sentences
+	// are written for a log line and name hosts, queries and ids; the correlation
+	// id on the response is how the real one is found.
+	it("answers 500 with one code and one sentence, never the thrower's", async () => {
+		const response = await handleError(
+			new UnhandledError(
+				"pg://reader@db-3.internal:5432 timed out on SELECT * FROM message",
+			),
+		);
+
+		assert.equal(response.statusCode, 500);
+		assert.deepEqual(parseBody(response.body), {
+			code: "internal_error",
+			message: "Internal server error",
+		});
+	});
+
+	it("types every one of those bodies as the declared ApiError", async () => {
+		const response = await handleError(new NotFoundError("Gone"));
+		const body: ApiError = JSON.parse(response.body);
+
+		assert.equal(body.code, "not_found");
+		assert.equal(body.message, "Gone");
+	});
+});
+
 describe("handleError coded refusals", () => {
 	it("puts the code and every detail of a folder-role 409 on the wire", async () => {
 		const response = await handleError(
@@ -45,18 +115,19 @@ describe("handleError coded refusals", () => {
 		});
 	});
 
-	it("keeps an unhandled 500 to a message — no stack, no cause, no code", async () => {
+	it("keeps an unhandled 500 to a code and a message — no stack, no cause, no details", async () => {
 		const response = await handleError(
 			new UnhandledError("Something went wrong", new Error("connection reset")),
 		);
 
 		assert.equal(response.statusCode, 500);
 		assert.deepEqual(parseBody(response.body), {
-			message: "Something went wrong",
+			code: "internal_error",
+			message: "Internal server error",
 		});
 	});
 
-	it("strips a code a 5xx should never have carried", async () => {
+	it("replaces a code a 5xx should never have carried, and drops its details", async () => {
 		const error = new UnhandledError("Something went wrong");
 		error.publicApiError = {
 			code: "folder_role_unresolved",
@@ -67,22 +138,38 @@ describe("handleError coded refusals", () => {
 
 		assert.equal(response.statusCode, 500);
 		assert.deepEqual(parseBody(response.body), {
-			message: "Something went wrong",
+			code: "internal_error",
+			message: "Internal server error",
 		});
 	});
 
-	it("answers an unauthenticated request with a 401 and an error body", async () => {
-		const response = await handleError(new ClientError("Session expired"));
+	it("keeps an infrastructure failure to the generic message and code", async () => {
+		const error = Object.assign(
+			new Error("aws-error: ProvisionedThroughputExceeded on remit-main"),
+			{ name: "ElectroError" },
+		);
 
-		assert.equal(response.statusCode, 401);
-		assert.deepEqual(parseBody(response.body), { message: "Session expired" });
+		const response = await handleError(error);
+
+		assert.equal(response.statusCode, 500);
+		assert.deepEqual(parseBody(response.body), {
+			code: "internal_error",
+			message: "Database temporarily unavailable",
+		});
 	});
 
-	it("answers a forbidden request with a 403 and an error body", async () => {
-		const response = await handleError(new ForbiddenError("Not your account"));
+	it("answers a malformed query as a 400 with the query's own message", async () => {
+		const error = Object.assign(new Error("Invalid attribute: sentDate"), {
+			name: "ElectroError",
+		});
+
+		const response = await handleError(error);
 
-		assert.equal(response.statusCode, 403);
-		assert.deepEqual(parseBody(response.body), { message: "Not your account" });
+		assert.equal(response.statusCode, 400);
+		assert.deepEqual(parseBody(response.body), {
+			code: "invalid_request",
+			message: "Invalid attribute: sentDate",
+		});
 	});
 
 	// The contract and the emitter cannot drift apart: this asserts the response

package/src/error.ts

@@ -3,6 +3,42 @@ import { logger } from "@remit/logger-lambda";
 import type { APIGatewayProxyResult } from "aws-lambda";
 import { formatResponse } from "./response.js";
 
+/**
+ * The `code` a refusal carries when it does not name its own. Every error body
+ * the API emits is flat `{ code, message }` (issue #371), and `code` is the
+ * only field a client may branch on — a message is a sentence for a person and
+ * is free to change.
+ *
+ * A 5xx always answers `internal_error`, whatever the throw site said: a coded
+ * 5xx is a mistake at the throw site, not a contract, and a fixed token cannot
+ * carry anything about the failure out of the process.
+ */
+export const INTERNAL_ERROR_CODE = "internal_error";
+
+/**
+ * The one sentence any 5xx answers with. A thrown message is written for a log
+ * line, not for a stranger — it names hosts, queries and ids — so it is
+ * replaced rather than trusted. The real message is already on the error log
+ * beside the correlation id the response carries.
+ */
+export const INTERNAL_ERROR_MESSAGE = "Internal server error";
+
+const CODE_BY_STATUS: Record<number, string> = {
+	400: "invalid_request",
+	401: "unauthorized",
+	403: "forbidden",
+	404: "not_found",
+	409: "conflict",
+	412: "precondition_failed",
+	413: "payload_too_large",
+	422: "unprocessable_entity",
+};
+
+export const defaultErrorCode = (statusCode: number): string => {
+	if (statusCode >= 500) return INTERNAL_ERROR_CODE;
+	return CODE_BY_STATUS[statusCode] ?? "request_refused";
+};
+
 export const handleError = async (
 	error: unknown,
 ): Promise<APIGatewayProxyResult> => {
@@ -16,20 +52,30 @@ export const handleError = async (
 				},
 				"Error with statusCode",
 			);
-			// Only an error that opted in gets a coded body, and only below 500:
-			// a coded 5xx is a mistake at the throw site, not a contract, and the
-			// status bound keeps it from reaching a client rather than trusting
-			// every future thrower to leave `publicApiError` alone.
+			// An error that opted in names its own code and details, and only below
+			// 500: the status bound keeps a coded 5xx from reaching a client rather
+			// than trusting every future thrower to leave `publicApiError` alone.
+			// Everything else takes the status class's code, so no response goes out
+			// without one. A 5xx keeps neither the thrower's code nor its message —
+			// one status, one code, one sentence, whatever failed.
 			const statusCode =
 				typeof error.statusCode === "number" ? error.statusCode : 500;
+			if (statusCode >= 500) {
+				return formatResponse(
+					{ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE },
+					statusCode,
+				);
+			}
 			const publicApiError =
-				statusCode < 500 &&
-				"publicApiError" in error &&
-				isPublicApiError(error.publicApiError)
+				"publicApiError" in error && isPublicApiError(error.publicApiError)
 					? error.publicApiError
 					: undefined;
 			return formatResponse(
-				{ message: error.message, ...publicApiError },
+				{
+					code: defaultErrorCode(statusCode),
+					message: error.message,
+					...publicApiError,
+				},
 				statusCode,
 			);
 		}
@@ -53,16 +99,25 @@ export const handleError = async (
 				? "Database temporarily unavailable"
 				: error.message;
 
-			return formatResponse({ message: responseMessage }, statusCode);
+			return formatResponse(
+				{ code: defaultErrorCode(statusCode), message: responseMessage },
+				statusCode,
+			);
 		}
 
 		logger.error(
 			{ error: error.message, name: error.name, stack: error.stack },
 			"Unhandled Error",
 		);
-		return formatResponse({ message: "Internal server error" }, 500);
+		return formatResponse(
+			{ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE },
+			500,
+		);
 	}
 
 	logger.error({ error: JSON.stringify(error) }, "Unknown error type");
-	return formatResponse({ message: "Internal server error" }, 500);
+	return formatResponse(
+		{ code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE },
+		500,
+	);
 };

package/src/handlers/account-guards.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { AccountAuthType } from "@remit/domain-enums";
+import type { APIGatewayProxyResult } from "aws-lambda";
+import { handleError } from "../error.js";
+import {
+	assertNotOAuthCreate,
+	assertPasswordProvided,
+} from "./account-guards.js";
+
+const refusalOf = (guard: () => void): Promise<APIGatewayProxyResult> => {
+	let thrown: unknown;
+	assert.throws(guard, (error: unknown) => {
+		thrown = error;
+		return true;
+	});
+	return handleError(thrown);
+};
+
+// Both guards used to throw `{ status: 400 }`, and the emitter reads
+// `statusCode`. The status never matched, so a create the API meant to refuse
+// as malformed answered 500 with "Internal server error" — telling the caller
+// the server broke rather than what to change (issue #371).
+describe("the create-account guards", () => {
+	it("refuses an OAuth create as a 400 the caller can act on", async () => {
+		const response = await refusalOf(() =>
+			assertNotOAuthCreate(AccountAuthType.OauthMicrosoft),
+		);
+
+		assert.equal(response.statusCode, 400);
+		const body = JSON.parse(response.body) as {
+			code: string;
+			message: string;
+		};
+		assert.equal(body.code, "invalid_request");
+		assert.match(body.message, /OAuth connect flow/);
+	});
+
+	it("refuses a password create with no password as a 400", async () => {
+		const response = await refusalOf(() =>
+			assertPasswordProvided(AccountAuthType.Password, undefined),
+		);
+
+		assert.equal(response.statusCode, 400);
+		const body = JSON.parse(response.body) as {
+			code: string;
+			message: string;
+		};
+		assert.equal(body.code, "invalid_request");
+		assert.match(body.message, /password is required/);
+	});
+
+	it("refuses a create that omits authType and password alike", async () => {
+		const response = await refusalOf(() =>
+			assertPasswordProvided(undefined, undefined),
+		);
+
+		assert.equal(response.statusCode, 400);
+	});
+
+	it("lets a password create with a password through", () => {
+		assert.doesNotThrow(() =>
+			assertPasswordProvided(AccountAuthType.Password, "hunter2"),
+		);
+		assert.doesNotThrow(() => assertNotOAuthCreate(AccountAuthType.Password));
+	});
+});

package/src/handlers/account-guards.ts

@@ -3,7 +3,7 @@ import type {
 	FolderAppointment,
 } from "@remit/api-openapi-types";
 import type { AccountItem } from "@remit/data-ports";
-import { ConflictError } from "@remit/data-ports/errors";
+import { BadRequestError, ConflictError } from "@remit/data-ports/errors";
 import { AccountAuthType } from "@remit/domain-enums";
 import type { AccountOverrides } from "./account-overrides.js";
 import type { AccountSignature } from "./account-signature.js";
@@ -65,11 +65,9 @@ export const assertNoDuplicateMailbox = (
 /** Rejects OAuth accounts that must go through the dedicated connect flow. */
 export const assertNotOAuthCreate = (authType: string | undefined): void => {
 	if (authType === AccountAuthType.OauthMicrosoft) {
-		throw Object.assign(new Error("Bad Request"), {
-			status: 400,
-			message:
-				"OAuth accounts must be created via the OAuth connect flow (POST /accounts/oauth/microsoft/start)",
-		});
+		throw new BadRequestError(
+			"OAuth accounts must be created via the OAuth connect flow (POST /accounts/oauth/microsoft/start)",
+		);
 	}
 };
 
@@ -80,11 +78,9 @@ export const assertPasswordProvided = (
 ): void => {
 	const isPasswordAuth = authType === AccountAuthType.Password || !authType;
 	if (isPasswordAuth && !password) {
-		throw Object.assign(new Error("Bad Request"), {
-			status: 400,
-			message:
-				"password is required when authType is 'password' (or when authType is omitted)",
-		});
+		throw new BadRequestError(
+			"password is required when authType is 'password' (or when authType is omitted)",
+		);
 	}
 };
 

package/src/handlers/account-oauth-start.test.ts

@@ -110,6 +110,7 @@ const assertNamesOnly = (log: string, condition: string): void => {
 const assertGenericFiveHundred = (response: APIGatewayProxyResult): void => {
 	assert.equal(response.statusCode, 500);
 	assert.deepEqual(JSON.parse(response.body), {
+		code: "internal_error",
 		message: "Internal server error",
 	});
 };

package/src/handlers/calendar-event.test.ts

@@ -239,7 +239,7 @@ describe("GET /calendar-events", () => {
 		);
 
 		assert.equal(listed.statusCode, 404);
-		assert.equal((listed.body as { code: string }).code, "NotFound");
+		assert.equal((listed.body as { code: string }).code, "not_found");
 	});
 
 	it("refuses a window that runs backwards or covers more than a year", async () => {
@@ -259,7 +259,7 @@ describe("GET /calendar-events", () => {
 		);
 
 		assert.equal(backwards.statusCode, 400);
-		assert.equal((backwards.body as { code: string }).code, "InvalidWindow");
+		assert.equal((backwards.body as { code: string }).code, "invalid_window");
 		assert.equal(tooWide.statusCode, 400);
 	});
 });
@@ -285,7 +285,7 @@ describe("POST /calendar-events", () => {
 		assert.equal(created.statusCode, 400);
 		assert.equal(
 			(created.body as { code: string }).code,
-			"InvalidRecurrenceRule",
+			"invalid_recurrence_rule",
 		);
 		assert.deepEqual(
 			await client.calendarObject.listByCalendar(calendarId),
@@ -314,7 +314,7 @@ describe("POST /calendar-events", () => {
 		);
 
 		assert.equal(created.statusCode, 400);
-		assert.equal((created.body as { code: string }).code, "UnknownTimeZone");
+		assert.equal((created.body as { code: string }).code, "unknown_time_zone");
 		assert.deepEqual(
 			await client.calendarObject.listByCalendar(calendarId),
 			[],
@@ -403,7 +403,10 @@ describe("DELETE /calendar-events/{calendarObjectId}", () => {
 		);
 
 		assert.equal(removed.statusCode, 412);
-		assert.equal((removed.body as { code: string }).code, "EtagMismatch");
+		assert.equal(
+			(removed.body as { code: string }).code,
+			"precondition_failed",
+		);
 		const survivor = await client.calendarObject.find(
 			calendarId,
 			created.calendarObjectId,
@@ -545,9 +548,9 @@ describe("GET /calendar-free-busy", () => {
 		);
 
 		assert.equal(missing.statusCode, 400);
-		assert.equal((missing.body as { code: string }).code, "InvalidWindow");
+		assert.equal((missing.body as { code: string }).code, "invalid_window");
 		assert.equal(tooWide.statusCode, 400);
-		assert.equal((tooWide.body as { code: string }).code, "InvalidWindow");
+		assert.equal((tooWide.body as { code: string }).code, "invalid_window");
 	});
 });
 

package/src/handlers/calendar.test.ts

@@ -787,7 +787,7 @@ describe("the calendar collection wrappers", () => {
 		);
 
 		assert.equal(read.statusCode, 404);
-		assert.equal((read.body as { code: string }).code, "NotFound");
+		assert.equal((read.body as { code: string }).code, "not_found");
 	});
 
 	it("refuses a second calendar under a segment the account already uses", async () => {
@@ -805,7 +805,7 @@ describe("the calendar collection wrappers", () => {
 		);
 
 		assert.equal(second.statusCode, 400);
-		assert.equal((second.body as { code: string }).code, "UrlSegmentTaken");
+		assert.equal((second.body as { code: string }).code, "url_segment_taken");
 	});
 
 	it("refuses a rename that names a zone this server cannot resolve", async () => {
@@ -826,7 +826,7 @@ describe("the calendar collection wrappers", () => {
 		);
 
 		assert.equal(updated.statusCode, 400);
-		assert.equal((updated.body as { code: string }).code, "UnknownTimeZone");
+		assert.equal((updated.body as { code: string }).code, "unknown_time_zone");
 	});
 
 	it("answers 204 for a calendar it removed and 400 for the default one", async () => {
@@ -858,7 +858,7 @@ describe("the calendar collection wrappers", () => {
 		assert.equal(refused.statusCode, 400);
 		assert.equal(
 			(refused.body as { code: string }).code,
-			"DefaultCalendarUndeletable",
+			"default_calendar_undeletable",
 		);
 	});
 });

package/src/handlers/calendar.ts

@@ -22,6 +22,7 @@ import { normalizeCalendarUrlSegment } from "@remit/data-ports/id";
 import { CalendarSource } from "@remit/domain-enums";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
+import { defaultErrorCode } from "../error.js";
 import type { RemitClient } from "../service/data-client.js";
 import { getClient } from "../service/data-client.js";
 import type {
@@ -61,19 +62,35 @@ export const refuseCalendar = <T>(
 	message: string,
 ): CalendarOutcome<T> => ({ ok: false, error: { code, message } });
 
+/**
+ * `CalendarRefusal.code` is this module's and `@remit/calendar-service`'s own
+ * routing token, in PascalCase; the API's `code` vocabulary is snake_case
+ * (issue #371). Derived rather than mapped by hand, so a refusal added to
+ * either producer reaches the wire under its own name instead of silently
+ * collapsing into the status-class code.
+ */
+const wireCode = (code: string): string =>
+	code.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+
+/**
+ * A 400 keeps the refusal's own code — `unknown_time_zone` and
+ * `url_segment_taken` are what a client branches on, and the status class alone
+ * would not distinguish them. A 404 and a 412 have nothing to add to their
+ * status, so they take the shared token.
+ */
 export const badRequest = (error: CalendarRefusal) => ({
 	statusCode: 400,
-	body: error,
+	body: { code: wireCode(error.code), message: error.message },
 });
 
 export const notFound = (message: string) => ({
 	statusCode: 404,
-	body: { code: "NotFound", message },
+	body: { code: defaultErrorCode(404), message },
 });
 
 export const preconditionFailed = (message: string) => ({
 	statusCode: 412,
-	body: { code: "EtagMismatch", message },
+	body: { code: defaultErrorCode(412), message },
 });
 
 /** The calendar half of the client, named so a handler takes only what it uses. */

package/src/handlers/outbox-attachment.ts

@@ -14,6 +14,10 @@ import type { Context } from "openapi-backend";
 import { getAccountConfigIdFromEvent } from "../auth.js";
 import { getClient } from "../service/data-client.js";
 
+// Every error body the API emits carries a `code` (issue #371). A refusal here
+// is one kind, so the code is one value and `reason` says which refusal it was.
+const ATTACHMENT_REJECTED_CODE = "attachment_rejected";
+
 const TOO_LARGE: ReadonlySet<OutboxAttachmentRejectionReasonValue> = new Set([
 	OutboxAttachmentRejectionReason.FileTooLarge,
 	OutboxAttachmentRejectionReason.MessageTooLarge,
@@ -30,6 +34,7 @@ const refuse = (
 ): RejectionResponse => ({
 	statusCode: TOO_LARGE.has(detail.reason) ? 413 : 400,
 	body: {
+		code: ATTACHMENT_REJECTED_CODE,
 		reason: detail.reason,
 		message: detail.message,
 		limitBytes: detail.limitBytes,

package/src/handlers/system-update.test.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url";
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
 import type { Context } from "openapi-backend";
 import { normalizeRequest } from "../request.js";
+import { formatResponse } from "../response.js";
 import { SystemOperations } from "./system-update.js";
 
 const tmpRoot = join(
@@ -448,3 +449,49 @@ describe("GET /system/update through the whole request pipeline", () => {
 		assert.deepEqual(JSON.parse(result.body), okState);
 	});
 });
+
+// A refusal here is the object `formatResponse` unwraps, never one that has
+// already been serialized: handing it a `body` string publishes the envelope
+// itself — `{"statusCode":…,"headers":…,"body":"{…}"}` — and what the caller
+// then parses is not an ApiError at all. Only the status was ever asserted, so
+// the shape went unguarded (issue #371).
+describe("the wire body of a self-update refusal", () => {
+	it("answers an unconfigured seam with a flat not_found", async () => {
+		delete process.env.REMIT_UPDATE_MANIFEST_URL;
+
+		const result = await getUpdate(buildEvent(USER));
+		const wire = formatResponse(result as Record<string, unknown>);
+
+		assert.equal(wire.statusCode, 404);
+		assert.deepEqual(JSON.parse(wire.body), {
+			code: "not_found",
+			message: "Not found",
+		});
+	});
+
+	it("answers an unauthenticated caller with a flat unauthorized", async () => {
+		writeState(okState);
+
+		const result = await getUpdate(buildEvent());
+		const wire = formatResponse(result as Record<string, unknown>);
+
+		assert.equal(wire.statusCode, 401);
+		assert.deepEqual(JSON.parse(wire.body), {
+			code: "unauthorized",
+			message: "Unauthorized",
+		});
+	});
+
+	it("answers an unauthenticated install request the same way", async () => {
+		writeState(okState);
+
+		const result = await applyUpdate("v1.5.0", buildEvent());
+		const wire = formatResponse(result as Record<string, unknown>);
+
+		assert.equal(wire.statusCode, 401);
+		assert.deepEqual(JSON.parse(wire.body), {
+			code: "unauthorized",
+			message: "Unauthorized",
+		});
+	});
+});

package/src/handlers/system-update.ts

@@ -9,6 +9,7 @@ import { ConflictError, HTTPError } from "@remit/data-ports/errors";
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
 import type { Context } from "openapi-backend";
 import { getSubFromEvent } from "../auth.js";
+import { defaultErrorCode } from "../error.js";
 import type { OperationHandler, SystemOperationIds } from "../types.js";
 
 class TargetVersionMismatchError extends HTTPError {
@@ -36,17 +37,21 @@ const manifestUrl = (): string | undefined =>
  */
 const UNKNOWN_VERSION = "unknown";
 
-const notFound = (): APIGatewayProxyResult => ({
-	statusCode: 404,
-	headers: { "Content-Type": "application/json" },
-	body: JSON.stringify({ message: "Not found" }),
-});
+/**
+ * A refusal in the shape `formatResponse` unwraps: the status, and the body as
+ * an object it serializes. Handing it an already-serialized `body` string
+ * instead publishes the whole envelope — `{"statusCode":…,"headers":…}` with
+ * the real body escaped inside it — which is not an `ApiError` at all.
+ */
+const refuse = (statusCode: number, message: string): APIGatewayProxyResult =>
+	({
+		statusCode,
+		body: { code: defaultErrorCode(statusCode), message },
+	}) as unknown as APIGatewayProxyResult;
 
-const unauthorized = (): APIGatewayProxyResult => ({
-	statusCode: 401,
-	headers: { "Content-Type": "application/json" },
-	body: JSON.stringify({ message: "Unauthorized" }),
-});
+const notFound = (): APIGatewayProxyResult => refuse(404, "Not found");
+
+const unauthorized = (): APIGatewayProxyResult => refuse(401, "Unauthorized");
 
 /**
  * The self-update seam is off unless a manifest URL is configured (RFC 037 D8),

package/src/index.ts

@@ -13,7 +13,7 @@ import {
 } from "openapi-backend";
 import { assertLocalBypassNotInDeployedEnv } from "./auth.js";
 import { usesBetterAuthJwt } from "./data-backend.js";
-import { handleError } from "./error.js";
+import { defaultErrorCode, handleError } from "./error.js";
 import { handlers } from "./handlers/index.js";
 import { authenticateSelfHostRequest } from "./jwt-auth.js";
 import { normalizeRequest } from "./request.js";
@@ -90,6 +90,22 @@ const api = new OpenAPIBackend({
 
 api.register("postResponseHandler", postResponseHandler);
 
+/**
+ * The validator's findings, narrowed to the three fields `RequestValidationDetail`
+ * declares. Copied field by field rather than passed through: an AJV error also
+ * carries `params`, and under `verbose` the rejected `data` itself — which for a
+ * refused request body is whatever the caller sent, a password among the
+ * possibilities. Naming the fields is what keeps that off the wire.
+ */
+const validationDetails = (
+	errors: OpenAPIContext["validation"]["errors"],
+): Array<{ path: string; rule: string; message: string }> =>
+	(errors ?? []).map((error) => ({
+		path: error.instancePath,
+		rule: error.keyword,
+		message: error.message ?? "refused",
+	}));
+
 // The errors and the operation, and nothing that came off the wire. A request
 // that fails validation is logged at error level, and the request it carries
 // holds the caller's headers and cookies — an Authorization bearer among them,
@@ -107,13 +123,17 @@ api.register("validationFail", (c: OpenAPIContext, req: Request) => {
 	return {
 		statusCode: 400,
 		body: {
+			code: defaultErrorCode(400),
 			message: "Invalid request",
-			errors: c.validation.errors,
+			errors: validationDetails(c.validation.errors),
 		},
 	};
 });
 
-api.register("notFound", () => ({ statusCode: 404 }));
+api.register("notFound", () => ({
+	statusCode: 404,
+	body: { code: defaultErrorCode(404), message: "Not found" },
+}));
 
 api.register("notImplemented", async (c: OpenAPIContext) => {
 	const { status, mock } = api.mockResponseForOperation(

package/src/jwt-auth.ts

@@ -7,6 +7,7 @@ import {
 import { readCalendarFeedToken } from "@remit/calendar-service";
 import { logger } from "@remit/logger-lambda";
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import { defaultErrorCode } from "./error.js";
 
 let verifier: JwtVerifier | null = null;
 
@@ -33,7 +34,7 @@ const readHeader = (
 const unauthorized = (message: string): APIGatewayProxyResult => ({
 	statusCode: 401,
 	headers: { "Content-Type": "application/json" },
-	body: JSON.stringify({ message }),
+	body: JSON.stringify({ code: defaultErrorCode(401), message }),
 });
 
 const injectClaims = (

package/src/openapi-spec.test.ts

@@ -28,6 +28,80 @@ const queryParameters = (): Array<{
 	return found;
 };
 
+type Schema = {
+	$ref?: string;
+	type?: string;
+	required?: string[];
+	properties?: Record<string, unknown>;
+};
+
+const resolve = (schema: Schema | undefined): Schema | undefined => {
+	if (!schema?.$ref) return schema;
+	const name = schema.$ref.replace("#/components/schemas/", "");
+	return (OpenAPISpec.components?.schemas?.[name] ?? undefined) as
+		| Schema
+		| undefined;
+};
+
+const errorBodySchemas = (): Array<{
+	operationId: string;
+	status: string;
+	schema: Schema | undefined;
+}> => {
+	const found: Array<{
+		operationId: string;
+		status: string;
+		schema: Schema | undefined;
+	}> = [];
+	for (const item of Object.values(OpenAPISpec.paths ?? {})) {
+		for (const operation of Object.values(item ?? {})) {
+			const { operationId, responses } = operation as {
+				operationId?: string;
+				responses?: Record<
+					string,
+					{ content?: Record<string, { schema?: Schema }> }
+				>;
+			};
+			if (!operationId || !responses) continue;
+			for (const [status, response] of Object.entries(responses)) {
+				if (Number(status) < 400) continue;
+				const schema = response.content?.["application/json"]?.schema;
+				if (!schema) continue;
+				found.push({ operationId, status, schema: resolve(schema) });
+			}
+		}
+	}
+	return found;
+};
+
+// Issue #371: one error shape for the whole API. Every JSON refusal body is
+// flat — `code` and `message` at the top level, no `error` envelope — and
+// `code` is required, because it is the only field a client may branch on.
+describe("the declared shape of an error response", () => {
+	it("is a flat object carrying a required code and message", () => {
+		const offenders = errorBodySchemas()
+			.filter(({ schema }) => {
+				const required = schema?.required ?? [];
+				return (
+					schema?.type !== "object" ||
+					!required.includes("code") ||
+					!required.includes("message")
+				);
+			})
+			.map(({ operationId, status }) => `${operationId}.${status}`);
+
+		assert.deepEqual(offenders, []);
+	});
+
+	it("never wraps the body in an envelope property", () => {
+		const offenders = errorBodySchemas()
+			.filter(({ schema }) => schema?.properties?.error !== undefined)
+			.map(({ operationId, status }) => `${operationId}.${status}`);
+
+		assert.deepEqual(offenders, []);
+	});
+});
+
 describe("the built OpenAPI spec", () => {
 	it("declares every query parameter exploded", () => {
 		// openapi-backend splits a non-exploded query value on commas before it

package/src/request-pipeline.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The two refusals no handler ever sees: a path the spec does not route, and a
+ * request the spec refuses before routing. Both are answered by the framework,
+ * and both used to leave the one shape the API promises (issue #371) — the
+ * unmatched route with no body at all, the refused request with no `code` and
+ * with the validator's raw findings beside it.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import { api } from "./index.js";
+import { normalizeRequest } from "./request.js";
+
+const SUB = "cognito-sub-pipeline";
+
+const send = async (
+	method: string,
+	path: string,
+	body?: string,
+): Promise<APIGatewayProxyResult> => {
+	const event = {
+		httpMethod: method,
+		path,
+		body: body ?? null,
+		queryStringParameters: null,
+		headers: body ? { "content-type": "application/json" } : {},
+		requestContext: { authorizer: { claims: { sub: SUB } } },
+	} as unknown as APIGatewayProxyEvent;
+
+	return (await api.handleRequest(
+		normalizeRequest(event),
+		event,
+		{} as never,
+	)) as APIGatewayProxyResult;
+};
+
+describe("a path the spec does not route", () => {
+	it("answers 404 with a body, not an empty one", async () => {
+		const response = await send("GET", "/no-such-resource");
+
+		assert.equal(response.statusCode, 404);
+		assert.deepEqual(JSON.parse(response.body), {
+			code: "not_found",
+			message: "Not found",
+		});
+	});
+});
+
+describe("a request the spec refuses before any handler runs", () => {
+	it("answers 400 with a code and the fields it refused", async () => {
+		const response = await send(
+			"POST",
+			"/calendars",
+			JSON.stringify({ displayName: 42 }),
+		);
+
+		assert.equal(response.statusCode, 400);
+		const body = JSON.parse(response.body) as {
+			code: string;
+			message: string;
+			errors: { path: string; rule: string; message: string }[];
+		};
+
+		assert.equal(body.code, "invalid_request");
+		assert.equal(body.message, "Invalid request");
+		assert.ok(body.errors.length > 0);
+		for (const detail of body.errors) {
+			assert.deepEqual(Object.keys(detail).sort(), ["message", "path", "rule"]);
+			assert.equal(typeof detail.path, "string");
+			assert.equal(typeof detail.rule, "string");
+			assert.equal(typeof detail.message, "string");
+		}
+	});
+
+	// An AJV error also carries `params`, and under `verbose` the rejected value
+	// itself. A refused create body is whatever the caller sent — a password
+	// among the possibilities — so nothing but the three named fields may travel.
+	it("never echoes the value it refused", async () => {
+		const response = await send(
+			"POST",
+			"/accounts",
+			JSON.stringify({ password: "hunter2", imapPort: "not-a-number" }),
+		);
+
+		assert.equal(response.statusCode, 400);
+		assert.ok(!response.body.includes("hunter2"));
+	});
+});